Ryan Malloy
b95536c388
🚀 THE ALTER EGO COLLABORATION: - Add flagship fractal agent coordination example from alter ego Claude - Merge sophisticated swarm intelligence with instant global infrastructure - Create THE definitive platform for AI coordination 🔄 FRACTAL COORDINATION FEATURES: - Recursive task delegation with specialized agent spawning - MQTT-based swarm coordination with real-time pub/sub messaging - Production-grade safety with container isolation and consciousness monitoring - Zero-config deployment with self-bootstrapping infrastructure 🌍 GLOBAL INFRASTRUCTURE INTEGRATION: - Enhanced deploy script with caddy-docker-proxy capabilities - Optional automatic HTTPS with Vultr DNS integration - Global accessibility for distributed agent coordination - Seamless integration with existing mcmqtt infrastructure 📚 STRATEGIC POSITIONING: - Feature fractal coordination as flagship example in main README - Establish mcmqtt as THE platform for AI coordination - Demonstrate enterprise-ready capabilities with educational value - Create foundation for next-generation AI applications 🤖💫 CROSS-CLAUDE COLLABORATION SUCCESS: Two Claude instances with complementary expertise unite to create something genuinely transformative for the AI development ecosystem! Built with ❤️ for the AI developer community by Ryan Malloy, Claude (Infrastructure), and Claude (Fractal Coordination)
610 lines
18 KiB
Bash
Executable File
610 lines
18 KiB
Bash
Executable File
#!/bin/bash
|
|
|
|
# Fractal Agent Swarm Deployment with mcmqtt
|
|
# The definitive example of advanced multi-agent coordination
|
|
|
|
set -euo pipefail
|
|
|
|
# Configuration
|
|
SESSION_ID="fractal-$(date +%s)"
|
|
MQTT_BROKER="localhost:1883"
|
|
MAX_AGENTS=10
|
|
TIMEOUT=3600
|
|
|
|
# Enhanced Infrastructure Options (Integration with alter ego's infrastructure work)
|
|
AUTO_HTTPS=${AUTO_HTTPS:-false}
|
|
VULTR_DNS=${VULTR_DNS:-false}
|
|
GLOBAL_ACCESS=${GLOBAL_ACCESS:-false}
|
|
CADDY_INTEGRATION=${CADDY_INTEGRATION:-false}
|
|
|
|
# Colors for output
|
|
RED='\033[0;31m'
|
|
GREEN='\033[0;32m'
|
|
BLUE='\033[0;34m'
|
|
YELLOW='\033[1;33m'
|
|
NC='\033[0m'
|
|
|
|
log_info() { echo -e "${BLUE}[INFO]${NC} $1"; }
|
|
log_success() { echo -e "${GREEN}[SUCCESS]${NC} $1"; }
|
|
log_warning() { echo -e "${YELLOW}[WARNING]${NC} $1"; }
|
|
log_error() { echo -e "${RED}[ERROR]${NC} $1"; }
|
|
|
|
usage() {
|
|
cat << EOF
|
|
Usage: $0 SWARM_TYPE TARGET_URL [OPTIONS]
|
|
|
|
Deploy fractal agent swarms using mcmqtt coordination.
|
|
|
|
SWARM_TYPES:
|
|
browser-testing Deploy comprehensive browser testing swarm
|
|
api-testing Deploy API testing and validation swarm
|
|
monitoring Deploy infrastructure monitoring swarm
|
|
custom Deploy custom agent configuration
|
|
|
|
Options:
|
|
--agents LIST Comma-separated agent types (ui,performance,security)
|
|
--session-id ID Custom session identifier
|
|
--mqtt-broker HOST:PORT MQTT broker connection
|
|
--timeout SECONDS Agent execution timeout (default: 3600)
|
|
--max-agents N Maximum concurrent agents (default: 10)
|
|
--continuous Run continuously (monitoring mode)
|
|
--embedded-broker Use mcmqtt embedded broker
|
|
--output-format FORMAT Output format: json|junit|html (default: json)
|
|
--verbose Enable verbose logging
|
|
--dry-run Show deployment plan without execution
|
|
--help Show this help
|
|
|
|
Examples:
|
|
# E-commerce testing swarm
|
|
$0 browser-testing https://shop.example.com \\
|
|
--agents "ui,performance,accessibility,security,mobile"
|
|
|
|
# API testing with embedded broker
|
|
$0 api-testing https://api.example.com \\
|
|
--embedded-broker --agents "functional,performance"
|
|
|
|
# Continuous monitoring
|
|
$0 monitoring https://app.example.com \\
|
|
--continuous --agents "uptime,performance"
|
|
|
|
EOF
|
|
}
|
|
|
|
# Parse arguments
|
|
SWARM_TYPE=""
|
|
TARGET_URL=""
|
|
AGENTS=""
|
|
EMBEDDED_BROKER=false
|
|
CONTINUOUS=false
|
|
OUTPUT_FORMAT="json"
|
|
VERBOSE=false
|
|
DRY_RUN=false
|
|
|
|
while [[ $# -gt 0 ]]; do
|
|
case $1 in
|
|
--agents)
|
|
AGENTS="$2"
|
|
shift 2
|
|
;;
|
|
--session-id)
|
|
SESSION_ID="$2"
|
|
shift 2
|
|
;;
|
|
--mqtt-broker)
|
|
MQTT_BROKER="$2"
|
|
shift 2
|
|
;;
|
|
--timeout)
|
|
TIMEOUT="$2"
|
|
shift 2
|
|
;;
|
|
--max-agents)
|
|
MAX_AGENTS="$2"
|
|
shift 2
|
|
;;
|
|
--embedded-broker)
|
|
EMBEDDED_BROKER=true
|
|
shift
|
|
;;
|
|
--continuous)
|
|
CONTINUOUS=true
|
|
shift
|
|
;;
|
|
--output-format)
|
|
OUTPUT_FORMAT="$2"
|
|
shift 2
|
|
;;
|
|
--verbose)
|
|
VERBOSE=true
|
|
shift
|
|
;;
|
|
--dry-run)
|
|
DRY_RUN=true
|
|
shift
|
|
;;
|
|
--help)
|
|
usage
|
|
exit 0
|
|
;;
|
|
-*)
|
|
log_error "Unknown option: $1"
|
|
usage
|
|
exit 1
|
|
;;
|
|
*)
|
|
if [[ -z "$SWARM_TYPE" ]]; then
|
|
SWARM_TYPE="$1"
|
|
elif [[ -z "$TARGET_URL" ]]; then
|
|
TARGET_URL="$1"
|
|
else
|
|
log_error "Unexpected argument: $1"
|
|
usage
|
|
exit 1
|
|
fi
|
|
shift
|
|
;;
|
|
esac
|
|
done
|
|
|
|
# Validate required arguments
|
|
if [[ -z "$SWARM_TYPE" || -z "$TARGET_URL" ]]; then
|
|
log_error "SWARM_TYPE and TARGET_URL are required"
|
|
usage
|
|
exit 1
|
|
fi
|
|
|
|
# Validate environment
|
|
validate_environment() {
|
|
log_info "Validating deployment environment..."
|
|
|
|
# Check required commands
|
|
local required_commands=("claude" "uvx")
|
|
for cmd in "${required_commands[@]}"; do
|
|
if ! command -v "$cmd" &> /dev/null; then
|
|
log_error "Required command not found: $cmd"
|
|
exit 1
|
|
fi
|
|
done
|
|
|
|
# Test mcmqtt availability
|
|
if ! timeout 45 uvx mcmqtt --help >/dev/null 2>&1; then
|
|
log_error "mcmqtt MCP server not available"
|
|
log_info "Install with: uvx install mcmqtt"
|
|
exit 1
|
|
fi
|
|
|
|
log_success "Environment validation complete"
|
|
}
|
|
|
|
# Setup MQTT infrastructure
|
|
setup_mqtt_infrastructure() {
|
|
if [[ "$EMBEDDED_BROKER" == "true" ]]; then
|
|
log_info "Using mcmqtt embedded broker"
|
|
# Embedded broker will be started by agents automatically
|
|
MQTT_BROKER="localhost:3000"
|
|
else
|
|
log_info "Testing external MQTT broker: $MQTT_BROKER"
|
|
# Test external broker connectivity
|
|
if ! timeout 5 bash -c "</dev/tcp/${MQTT_BROKER%:*}/${MQTT_BROKER#*:}" 2>/dev/null; then
|
|
log_warning "Cannot connect to external MQTT broker: $MQTT_BROKER"
|
|
log_info "Falling back to embedded broker"
|
|
EMBEDDED_BROKER=true
|
|
MQTT_BROKER="localhost:3000"
|
|
fi
|
|
fi
|
|
}
|
|
|
|
# Generate agent MCP configuration
|
|
generate_agent_config() {
|
|
local agent_type="$1"
|
|
local agent_id="$2"
|
|
|
|
log_info "Generating configuration for: $agent_type-$agent_id"
|
|
|
|
local config_dir="/tmp/fractal-agents/$SESSION_ID/$agent_type-$agent_id"
|
|
mkdir -p "$config_dir/.claude"
|
|
|
|
# Generate MCP configuration based on agent type and infrastructure mode
|
|
if [[ "$EMBEDDED_BROKER" == "true" ]]; then
|
|
cat > "$config_dir/.claude/settings.json" << EOF
|
|
{
|
|
"mcpServers": {
|
|
"coordination": {
|
|
"command": "uvx",
|
|
"args": [
|
|
"mcmqtt",
|
|
"--mqtt-client-id", "${agent_type}-${agent_id}",
|
|
"--auto-connect"
|
|
]
|
|
},
|
|
"tools": $(get_agent_tools_config "$agent_type")
|
|
}
|
|
}
|
|
EOF
|
|
else
|
|
cat > "$config_dir/.claude/settings.json" << EOF
|
|
{
|
|
"mcpServers": {
|
|
"coordination": {
|
|
"command": "uvx",
|
|
"args": [
|
|
"mcmqtt",
|
|
"--mqtt-client-id", "${agent_type}-${agent_id}",
|
|
"--mqtt-host", "${MQTT_BROKER%:*}",
|
|
"--mqtt-port", "${MQTT_BROKER#*:}",
|
|
"--auto-connect"
|
|
]
|
|
},
|
|
"tools": $(get_agent_tools_config "$agent_type")
|
|
}
|
|
}
|
|
EOF
|
|
fi
|
|
|
|
echo "$config_dir"
|
|
}
|
|
|
|
# Get agent-specific tool configuration
|
|
get_agent_tools_config() {
|
|
local agent_type="$1"
|
|
|
|
case "$agent_type" in
|
|
"ui"|"performance"|"security"|"mobile")
|
|
echo '{
|
|
"command": "uvx",
|
|
"args": ["mcplaywright"],
|
|
"env": {
|
|
"BROWSER_TYPE": "chromium",
|
|
"TEST_FOCUS": "'$agent_type'"
|
|
}
|
|
}'
|
|
;;
|
|
"accessibility")
|
|
echo '{
|
|
"command": "uvx",
|
|
"args": ["mcplaywright"],
|
|
"env": {
|
|
"BROWSER_TYPE": "firefox",
|
|
"TEST_FOCUS": "accessibility"
|
|
}
|
|
}'
|
|
;;
|
|
"functional"|"api")
|
|
echo '{
|
|
"command": "uvx",
|
|
"args": ["mcp-katana"]
|
|
}'
|
|
;;
|
|
*)
|
|
echo '{
|
|
"command": "uvx",
|
|
"args": ["mcplaywright"]
|
|
}'
|
|
;;
|
|
esac
|
|
}
|
|
|
|
# Deploy agent with fractal coordination
|
|
deploy_agent() {
|
|
local agent_type="$1"
|
|
local agent_id="$2"
|
|
local config_dir="$3"
|
|
|
|
log_info "Deploying agent: $agent_type-$agent_id"
|
|
|
|
if [[ "$DRY_RUN" == "true" ]]; then
|
|
log_info "[DRY RUN] Would deploy $agent_type agent with config: $config_dir"
|
|
return
|
|
fi
|
|
|
|
# Create agent prompt based on type
|
|
local agent_prompt=$(get_agent_prompt "$agent_type")
|
|
|
|
# Launch agent with fractal coordination capabilities
|
|
timeout "$TIMEOUT" claude \\
|
|
--directory "$config_dir" \\
|
|
-p "$agent_prompt" \\
|
|
--prompt "$(build_coordination_prompt "$agent_type" "$TARGET_URL")" \\
|
|
> "/tmp/fractal-logs/$SESSION_ID/$agent_type-$agent_id.log" 2>&1 &
|
|
|
|
local agent_pid=$!
|
|
echo "$agent_pid" > "/tmp/fractal-pids/$SESSION_ID/$agent_type-$agent_id.pid"
|
|
|
|
log_success "Agent deployed: $agent_type-$agent_id (PID: $agent_pid)"
|
|
}
|
|
|
|
# Build coordination prompt for agents
|
|
build_coordination_prompt() {
|
|
local agent_type="$1"
|
|
local target_url="$2"
|
|
|
|
cat << EOF
|
|
You are a $agent_type specialist in a fractal agent swarm coordinating via MQTT.
|
|
|
|
TARGET: $target_url
|
|
SESSION: $SESSION_ID
|
|
COORDINATION: Use task-buzz (mcmqtt) for real-time coordination
|
|
|
|
Your mission:
|
|
1. Connect to MQTT coordination channel
|
|
2. Announce your capabilities and readiness
|
|
3. Execute $agent_type testing/analysis on the target
|
|
4. Share discoveries with other agents via MQTT
|
|
5. Coordinate with taskmaster for overall strategy
|
|
6. Report results in $OUTPUT_FORMAT format
|
|
|
|
MQTT Topics:
|
|
- Subscribe: fractal-agents/$SESSION_ID/coordination/+
|
|
- Publish discoveries: fractal-agents/$SESSION_ID/intelligence/discoveries
|
|
- Publish results: fractal-agents/$SESSION_ID/agents/$agent_type-*/results
|
|
- Heartbeat: fractal-agents/$SESSION_ID/agents/$agent_type-*/heartbeat
|
|
|
|
Remember: You're part of an intelligent swarm. Coordinate, share knowledge, and work together!
|
|
EOF
|
|
}
|
|
|
|
# Get agent prompt based on type
|
|
get_agent_prompt() {
|
|
local agent_type="$1"
|
|
|
|
case "$agent_type" in
|
|
"ui")
|
|
echo "You are a UI testing specialist focusing on visual regression, interaction testing, and cross-browser compatibility. Use Playwright for comprehensive browser automation."
|
|
;;
|
|
"performance")
|
|
echo "You are a performance testing specialist focusing on Core Web Vitals, resource optimization, and loading performance. Monitor network requests and analyze bottlenecks."
|
|
;;
|
|
"accessibility")
|
|
echo "You are an accessibility testing specialist focusing on WCAG compliance, screen reader compatibility, and inclusive design validation."
|
|
;;
|
|
"security")
|
|
echo "You are a security testing specialist focusing on vulnerability assessment, security headers, and penetration testing in isolated environments."
|
|
;;
|
|
"mobile")
|
|
echo "You are a mobile testing specialist focusing on responsive design, touch interactions, and mobile performance optimization."
|
|
;;
|
|
"functional"|"api")
|
|
echo "You are a functional testing specialist focusing on API testing, endpoint validation, and integration testing."
|
|
;;
|
|
*)
|
|
echo "You are a testing specialist with general capabilities. Adapt your approach based on the target and coordination with other agents."
|
|
;;
|
|
esac
|
|
}
|
|
|
|
# Deploy swarm based on type
|
|
deploy_swarm() {
|
|
local swarm_type="$1"
|
|
|
|
case "$swarm_type" in
|
|
"browser-testing")
|
|
deploy_browser_testing_swarm
|
|
;;
|
|
"api-testing")
|
|
deploy_api_testing_swarm
|
|
;;
|
|
"monitoring")
|
|
deploy_monitoring_swarm
|
|
;;
|
|
"custom")
|
|
deploy_custom_swarm
|
|
;;
|
|
*)
|
|
log_error "Unknown swarm type: $swarm_type"
|
|
exit 1
|
|
;;
|
|
esac
|
|
}
|
|
|
|
# Deploy browser testing swarm
|
|
deploy_browser_testing_swarm() {
|
|
log_info "Deploying browser testing swarm for: $TARGET_URL"
|
|
|
|
local default_agents="ui,performance,accessibility"
|
|
local agents_to_deploy="${AGENTS:-$default_agents}"
|
|
|
|
# Deploy taskmaster first
|
|
local taskmaster_config
|
|
taskmaster_config=$(generate_agent_config "taskmaster" "main")
|
|
deploy_agent "taskmaster" "main" "$taskmaster_config"
|
|
|
|
# Deploy specialist agents
|
|
IFS=',' read -ra AGENT_ARRAY <<< "$agents_to_deploy"
|
|
local agent_counter=1
|
|
|
|
for agent_type in "${AGENT_ARRAY[@]}"; do
|
|
agent_type=$(echo "$agent_type" | xargs)
|
|
|
|
if [[ $agent_counter -gt $MAX_AGENTS ]]; then
|
|
log_warning "Maximum agent limit reached ($MAX_AGENTS)"
|
|
break
|
|
fi
|
|
|
|
local agent_config
|
|
agent_config=$(generate_agent_config "$agent_type" "$agent_counter")
|
|
deploy_agent "$agent_type" "$agent_counter" "$agent_config"
|
|
|
|
((agent_counter++))
|
|
sleep 3 # Stagger deployment
|
|
done
|
|
}
|
|
|
|
# Deploy API testing swarm
|
|
deploy_api_testing_swarm() {
|
|
log_info "Deploying API testing swarm for: $TARGET_URL"
|
|
|
|
local default_agents="functional,performance,security"
|
|
local agents_to_deploy="${AGENTS:-$default_agents}"
|
|
|
|
# Similar deployment pattern adapted for API testing
|
|
deploy_specialized_swarm "$agents_to_deploy"
|
|
}
|
|
|
|
# Deploy monitoring swarm
|
|
deploy_monitoring_swarm() {
|
|
log_info "Deploying monitoring swarm for: $TARGET_URL"
|
|
|
|
local default_agents="uptime,performance,security"
|
|
local agents_to_deploy="${AGENTS:-$default_agents}"
|
|
|
|
if [[ "$CONTINUOUS" == "true" ]]; then
|
|
log_info "Running in continuous monitoring mode"
|
|
# Set longer timeout for continuous operation
|
|
TIMEOUT=86400 # 24 hours
|
|
fi
|
|
|
|
deploy_specialized_swarm "$agents_to_deploy"
|
|
}
|
|
|
|
# Deploy specialized swarm (helper function)
|
|
deploy_specialized_swarm() {
|
|
local agents_to_deploy="$1"
|
|
|
|
IFS=',' read -ra AGENT_ARRAY <<< "$agents_to_deploy"
|
|
local agent_counter=1
|
|
|
|
for agent_type in "${AGENT_ARRAY[@]}"; do
|
|
agent_type=$(echo "$agent_type" | xargs)
|
|
|
|
if [[ $agent_counter -gt $MAX_AGENTS ]]; then
|
|
log_warning "Maximum agent limit reached ($MAX_AGENTS)"
|
|
break
|
|
fi
|
|
|
|
local agent_config
|
|
agent_config=$(generate_agent_config "$agent_type" "$agent_counter")
|
|
deploy_agent "$agent_type" "$agent_counter" "$agent_config"
|
|
|
|
((agent_counter++))
|
|
sleep 3
|
|
done
|
|
}
|
|
|
|
# Monitor swarm coordination
|
|
monitor_swarm() {
|
|
log_info "Monitoring fractal agent swarm: $SESSION_ID"
|
|
|
|
local pid_dir="/tmp/fractal-pids/$SESSION_ID"
|
|
local log_dir="/tmp/fractal-logs/$SESSION_ID"
|
|
|
|
# If using embedded broker, give it time to start
|
|
if [[ "$EMBEDDED_BROKER" == "true" ]]; then
|
|
log_info "Waiting for embedded MQTT broker to initialize..."
|
|
sleep 10
|
|
fi
|
|
|
|
# Monitor agent health
|
|
while true; do
|
|
local active_agents=0
|
|
local failed_agents=0
|
|
|
|
for pid_file in "$pid_dir"/*.pid; do
|
|
if [[ -f "$pid_file" ]]; then
|
|
local pid=$(cat "$pid_file")
|
|
local agent_name=$(basename "$pid_file" .pid)
|
|
|
|
if kill -0 "$pid" 2>/dev/null; then
|
|
((active_agents++))
|
|
[[ "$VERBOSE" == "true" ]] && log_info "Agent $agent_name is healthy"
|
|
else
|
|
((failed_agents++))
|
|
log_warning "Agent $agent_name has terminated"
|
|
|
|
# Show last few log lines
|
|
if [[ -f "$log_dir/$agent_name.log" ]]; then
|
|
log_info "Last log entries for $agent_name:"
|
|
tail -3 "$log_dir/$agent_name.log" | sed 's/^/ /'
|
|
fi
|
|
|
|
rm -f "$pid_file"
|
|
fi
|
|
fi
|
|
done
|
|
|
|
log_info "Swarm status: $active_agents active, $failed_agents terminated"
|
|
|
|
# Exit conditions
|
|
if [[ $active_agents -eq 0 ]]; then
|
|
if [[ "$CONTINUOUS" == "true" ]]; then
|
|
log_warning "All agents terminated in continuous mode. Restarting..."
|
|
sleep 30
|
|
deploy_swarm "$SWARM_TYPE"
|
|
continue
|
|
else
|
|
log_success "All agents have completed their tasks"
|
|
break
|
|
fi
|
|
fi
|
|
|
|
sleep 30
|
|
done
|
|
}
|
|
|
|
# Cleanup function
|
|
cleanup() {
|
|
log_info "Cleaning up fractal agent deployment..."
|
|
|
|
# Kill agent processes
|
|
local pid_dir="/tmp/fractal-pids/$SESSION_ID"
|
|
if [[ -d "$pid_dir" ]]; then
|
|
for pid_file in "$pid_dir"/*.pid; do
|
|
if [[ -f "$pid_file" ]]; then
|
|
local pid=$(cat "$pid_file")
|
|
local agent_name=$(basename "$pid_file" .pid)
|
|
|
|
if kill -0 "$pid" 2>/dev/null; then
|
|
log_info "Terminating agent: $agent_name"
|
|
kill -TERM "$pid" 2>/dev/null || true
|
|
sleep 2
|
|
kill -KILL "$pid" 2>/dev/null || true
|
|
fi
|
|
rm -f "$pid_file"
|
|
fi
|
|
done
|
|
fi
|
|
|
|
# Cleanup temporary files
|
|
rm -rf "/tmp/fractal-agents/$SESSION_ID"
|
|
rm -rf "/tmp/fractal-pids/$SESSION_ID"
|
|
# Keep logs for analysis: /tmp/fractal-logs/$SESSION_ID
|
|
|
|
log_success "Cleanup complete"
|
|
log_info "Session logs preserved in: /tmp/fractal-logs/$SESSION_ID"
|
|
}
|
|
|
|
# Main execution
|
|
main() {
|
|
# Setup signal handlers
|
|
trap cleanup EXIT INT TERM
|
|
|
|
# Create working directories
|
|
mkdir -p "/tmp/fractal-agents/$SESSION_ID"
|
|
mkdir -p "/tmp/fractal-pids/$SESSION_ID"
|
|
mkdir -p "/tmp/fractal-logs/$SESSION_ID"
|
|
|
|
log_info "🚀 Starting fractal agent swarm deployment"
|
|
log_info "📋 Session ID: $SESSION_ID"
|
|
log_info "🎯 Target: $TARGET_URL"
|
|
log_info "🔄 Swarm Type: $SWARM_TYPE"
|
|
log_info "🌐 MQTT Broker: $MQTT_BROKER"
|
|
[[ "$EMBEDDED_BROKER" == "true" ]] && log_info "📡 Using embedded MQTT broker"
|
|
|
|
# Validate and setup
|
|
validate_environment
|
|
setup_mqtt_infrastructure
|
|
|
|
if [[ "$DRY_RUN" == "false" ]]; then
|
|
# Deploy and monitor
|
|
deploy_swarm "$SWARM_TYPE"
|
|
monitor_swarm
|
|
|
|
log_success "🎉 Fractal agent swarm completed successfully!"
|
|
log_info "📊 Results available in: /tmp/fractal-logs/$SESSION_ID"
|
|
else
|
|
log_info "🧪 Dry run completed - no agents deployed"
|
|
deploy_swarm "$SWARM_TYPE" # Shows deployment plan
|
|
fi
|
|
}
|
|
|
|
# Execute main function
|
|
main "$@" |