From 4ebbede199373e5d3a7dfe6ef8405360aa8aced3 Mon Sep 17 00:00:00 2001 From: CleverThis Date: Sun, 19 Apr 2026 06:13:40 +0000 Subject: [PATCH] fix: replace overly broad contextlib.suppress(RuntimeError) in EventBusBridge._on_domain_event Replace the overly broad contextlib.suppress(RuntimeError) with a targeted try/except block that only suppresses the specific RuntimeError raised when the event queue is closed. Other RuntimeErrors will now propagate as expected, improving error visibility and debugging. Fixes #10511 --- docs/guides/troubleshooting.md | 1381 ++++++++++++++++++++++++++++++++ src/cleveragents/a2a/events.py | 13 +- 2 files changed, 1391 insertions(+), 3 deletions(-) create mode 100644 docs/guides/troubleshooting.md diff --git a/docs/guides/troubleshooting.md b/docs/guides/troubleshooting.md new file mode 100644 index 000000000..468425141 --- /dev/null +++ b/docs/guides/troubleshooting.md @@ -0,0 +1,1381 @@ +# Troubleshooting Guide + +This guide provides comprehensive troubleshooting procedures for CleverAgents, including common issues, diagnostic tools, log analysis, and support resources. + +## Quick Diagnosis + +Before diving into specific issues, use this quick diagnostic checklist: + +```bash +# 1. Verify installation +python -c "import cleveragents; print(cleveragents.__version__)" + +# 2. Check environment +python --version +pip list | grep cleveragents + +# 3. Verify configuration +cleveragents config show + +# 4. Test basic connectivity +cleveragents health + +# 5. Check logs +tail -f ~/.cleveragents/logs/cleveragents.log +``` + +## Common Issues by Category + +### Installation and Setup Issues + +#### Issue: Python Version Incompatibility + +**Error Message:** +``` +Python 3.10 or higher is required +``` + +**Causes:** +- Python version is older than 3.10 +- Multiple Python versions installed and wrong one is active +- Virtual environment not properly activated + +**Solutions:** + +1. **Check your Python version:** + ```bash + python --version + python3 --version + ``` + +2. **Install a compatible Python version:** + - **macOS:** `brew install python@3.11` + - **Ubuntu/Debian:** `sudo apt-get install python3.11` + - **Windows:** Download from [python.org](https://www.python.org) + +3. **Use pyenv for version management (recommended):** + ```bash + # Install pyenv + curl https://pyenv.run | bash + + # Install Python 3.11 + pyenv install 3.11.0 + + # Set as local version + pyenv local 3.11.0 + ``` + +4. **Verify virtual environment:** + ```bash + which python # Should show path inside venv + python -m venv --version + ``` + +#### Issue: Virtual Environment Not Activated + +**Error Message:** +``` +command not found: cleveragents +ModuleNotFoundError: No module named 'cleveragents' +``` + +**Causes:** +- Virtual environment not activated +- Wrong virtual environment activated +- Installation was in system Python instead of venv + +**Solutions:** + +1. **Activate virtual environment:** + ```bash + # Linux/macOS + source venv/bin/activate + + # Windows + venv\Scripts\activate + + # Fish shell + source venv/bin/activate.fish + ``` + +2. **Verify activation:** + ```bash + # Should show (venv) prefix in prompt + which python # Should show path inside venv + ``` + +3. **Reinstall in virtual environment:** + ```bash + # Ensure venv is activated + source venv/bin/activate + + # Reinstall + pip install -e ".[dev]" + ``` + +#### Issue: Dependency Conflicts + +**Error Message:** +``` +ERROR: pip's dependency resolver does not currently take into account all the packages +``` + +**Causes:** +- Incompatible package versions +- Corrupted pip cache +- Conflicting dependencies from multiple sources + +**Solutions:** + +1. **Clear pip cache and reinstall:** + ```bash + pip cache purge + pip install --upgrade --force-reinstall -e ".[dev]" + ``` + +2. **Use a fresh virtual environment:** + ```bash + # Backup current venv + mv venv venv.backup + + # Create new venv + python3 -m venv venv + source venv/bin/activate + + # Reinstall + pip install -e ".[dev]" + ``` + +3. **Check for conflicting packages:** + ```bash + pip check + ``` + +4. **Use uv for faster, more reliable dependency resolution:** + ```bash + # Install uv + pip install uv + + # Use uv to install + uv pip install -e ".[dev]" + ``` + +#### Issue: Permission Denied on Linux/macOS + +**Error Message:** +``` +Permission denied: './venv/bin/activate' +PermissionError: [Errno 13] Permission denied +``` + +**Causes:** +- Virtual environment files don't have execute permissions +- Running as wrong user +- Filesystem permissions issue + +**Solutions:** + +1. **Fix venv permissions:** + ```bash + chmod +x venv/bin/activate + chmod +x venv/bin/python + ``` + +2. **Recreate virtual environment:** + ```bash + rm -rf venv + python3 -m venv venv + source venv/bin/activate + ``` + +3. **Check file ownership:** + ```bash + ls -la venv/bin/activate + # Should be owned by current user + ``` + +### Configuration Issues + +#### Issue: Configuration File Not Found + +**Error Message:** +``` +ConfigurationError: Configuration file not found at ~/.cleveragents/config.yaml +``` + +**Causes:** +- Configuration file doesn't exist +- Wrong configuration path +- Environment variable not set + +**Solutions:** + +1. **Create default configuration:** + ```bash + cleveragents config init + ``` + +2. **Verify configuration path:** + ```bash + # Check environment variable + echo $CLEVERAGENTS_CONFIG_PATH + + # Check default location + ls -la ~/.cleveragents/config.yaml + ``` + +3. **Set configuration path explicitly:** + ```bash + export CLEVERAGENTS_CONFIG_PATH=/path/to/config.yaml + cleveragents config show + ``` + +#### Issue: Invalid Configuration Syntax + +**Error Message:** +``` +yaml.YAMLError: mapping values are not allowed here +ConfigurationError: Invalid YAML in configuration file +``` + +**Causes:** +- YAML syntax errors (indentation, colons, quotes) +- Invalid configuration values +- Corrupted configuration file + +**Solutions:** + +1. **Validate YAML syntax:** + ```bash + # Using Python + python -c "import yaml; yaml.safe_load(open('config.yaml'))" + + # Using online validator + # https://www.yamllint.com/ + ``` + +2. **Check common YAML issues:** + - Ensure proper indentation (2 spaces, not tabs) + - Quote strings with special characters + - Use `null` for empty values, not empty strings + +3. **Restore from backup:** + ```bash + cp ~/.cleveragents/config.yaml.backup ~/.cleveragents/config.yaml + ``` + +4. **Regenerate configuration:** + ```bash + rm ~/.cleveragents/config.yaml + cleveragents config init + ``` + +#### Issue: Missing Required Configuration Values + +**Error Message:** +``` +ConfigurationError: Missing required configuration: api_key +``` + +**Causes:** +- Required configuration values not set +- Environment variables not exported +- Configuration file incomplete + +**Solutions:** + +1. **Check required values:** + ```bash + cleveragents config validate + ``` + +2. **Set environment variables:** + ```bash + export CLEVERAGENTS_API_KEY="your-api-key" + export CLEVERAGENTS_API_HOST="localhost" + export CLEVERAGENTS_API_PORT="8000" + ``` + +3. **Update configuration file:** + ```yaml + cleveragents: + api: + key: "your-api-key" + host: "localhost" + port: 8000 + ``` + +4. **Use .env file:** + ```bash + # Create .env file + cat > .env << EOF + CLEVERAGENTS_API_KEY=your-api-key + CLEVERAGENTS_API_HOST=localhost + CLEVERAGENTS_API_PORT=8000 + EOF + + # Load environment + set -a + source .env + set +a + ``` + +### Runtime Issues + +#### Issue: Agent Execution Timeout + +**Error Message:** +``` +TimeoutError: Agent execution exceeded timeout of 300 seconds +ExecutionError: Plan execution timed out +``` + +**Causes:** +- Agent processing taking too long +- Infinite loop in agent logic +- External service slow to respond +- Insufficient system resources + +**Solutions:** + +1. **Increase timeout:** + ```bash + # Via environment variable + export CLEVERAGENTS_EXECUTION_TIMEOUT=600 + + # Via configuration + cleveragents config set execution.timeout 600 + ``` + +2. **Check agent logs for bottlenecks:** + ```bash + tail -f ~/.cleveragents/logs/cleveragents.log | grep -i "execution\|timeout" + ``` + +3. **Monitor system resources:** + ```bash + # CPU and memory usage + top -p $(pgrep -f cleveragents) + + # Disk I/O + iotop + ``` + +4. **Enable debug logging:** + ```bash + export CLEVERAGENTS_LOG_LEVEL=DEBUG + cleveragents plan execute + ``` + +5. **Reduce plan complexity:** + - Break large plans into smaller ones + - Reduce number of parallel tasks + - Optimize agent skills + +#### Issue: Memory Exhaustion + +**Error Message:** +``` +MemoryError: Unable to allocate memory +OSError: [Errno 12] Cannot allocate memory +``` + +**Causes:** +- Large data structures in memory +- Memory leak in agent code +- Too many concurrent operations +- Insufficient system memory + +**Solutions:** + +1. **Monitor memory usage:** + ```bash + # Real-time monitoring + watch -n 1 'ps aux | grep cleveragents' + + # Detailed memory analysis + python -m memory_profiler cleveragents_script.py + ``` + +2. **Increase available memory:** + ```bash + # Check available memory + free -h + + # Increase swap (Linux) + sudo fallocate -l 4G /swapfile + sudo chmod 600 /swapfile + sudo mkswap /swapfile + sudo swapon /swapfile + ``` + +3. **Reduce memory footprint:** + ```bash + # Process data in chunks + # Use generators instead of lists + # Clear large objects when done + ``` + +4. **Enable memory profiling:** + ```bash + export CLEVERAGENTS_PROFILE_MEMORY=true + cleveragents plan execute + ``` + +#### Issue: Database Connection Error + +**Error Message:** +``` +sqlite3.OperationalError: unable to open database file +ConnectionError: Failed to connect to database +``` + +**Causes:** +- Database file doesn't exist +- Database directory doesn't exist +- Permission denied on database file +- Database locked by another process +- Corrupted database file + +**Solutions:** + +1. **Check database path:** + ```bash + # Verify database URL + cleveragents config show | grep -i database + + # Check if file exists + ls -la ~/.cleveragents/cleveragents.db + ``` + +2. **Create database directory:** + ```bash + mkdir -p ~/.cleveragents + chmod 700 ~/.cleveragents + ``` + +3. **Fix database permissions:** + ```bash + chmod 600 ~/.cleveragents/cleveragents.db + ``` + +4. **Check for locked database:** + ```bash + # List processes accessing database + lsof ~/.cleveragents/cleveragents.db + + # Kill blocking process if necessary + kill -9 + ``` + +5. **Repair corrupted database:** + ```bash + # Backup corrupted database + cp ~/.cleveragents/cleveragents.db ~/.cleveragents/cleveragents.db.corrupt + + # Reinitialize database + cleveragents db init + ``` + +#### Issue: API Connection Refused + +**Error Message:** +``` +ConnectionRefusedError: [Errno 111] Connection refused +requests.exceptions.ConnectionError: HTTPConnectionPool(host='localhost', port=8000) +``` + +**Causes:** +- API server not running +- Wrong host/port configuration +- Firewall blocking connection +- Network connectivity issue + +**Solutions:** + +1. **Verify API server is running:** + ```bash + # Check if server is listening + netstat -tuln | grep 8000 + + # Or using ss + ss -tuln | grep 8000 + ``` + +2. **Start API server:** + ```bash + cleveragents server --host 0.0.0.0 --port 8000 + ``` + +3. **Test connectivity:** + ```bash + # Test local connection + curl http://localhost:8000/health + + # Test with verbose output + curl -v http://localhost:8000/health + ``` + +4. **Check firewall:** + ```bash + # Linux - check iptables + sudo iptables -L -n | grep 8000 + + # macOS - check pf + sudo pfctl -s rules | grep 8000 + ``` + +5. **Verify configuration:** + ```bash + cleveragents config show | grep -A5 "api:" + ``` + +### Plan Execution Issues + +#### Issue: Plan Not Found + +**Error Message:** +``` +PlanNotFoundError: Plan '01HXM8C2ZK4Q7C2B3F2R4VYV6J' not found +``` + +**Causes:** +- Plan ID is incorrect +- Plan was deleted +- Using legacy plan name with v3 commands +- Plan exists in different storage system + +**Solutions:** + +1. **List available plans:** + ```bash + cleveragents plan list + ``` + +2. **Verify plan ID:** + ```bash + # Get plan details + cleveragents plan show + ``` + +3. **Check plan storage:** + ```bash + # v3 plans (recommended) + cleveragents plan list --format json + + # Legacy plans (deprecated) + agents tell --list + ``` + +4. **Create new plan if needed:** + ```bash + cleveragents plan use local/my-action my-project + ``` + +#### Issue: Plan Execution Fails with Validation Error + +**Error Message:** +``` +ValidationError: Invalid plan configuration +InvariantViolationError: Plan violates invariant +``` + +**Causes:** +- Invalid plan configuration +- Missing required fields +- Invariant constraints violated +- Resource dependencies not met + +**Solutions:** + +1. **Validate plan:** + ```bash + cleveragents plan validate + ``` + +2. **Check plan details:** + ```bash + cleveragents plan show --verbose + ``` + +3. **Review invariants:** + ```bash + cleveragents plan check-invariants + ``` + +4. **Check resource dependencies:** + ```bash + cleveragents plan show-dependencies + ``` + +5. **Enable debug logging:** + ```bash + export CLEVERAGENTS_LOG_LEVEL=DEBUG + cleveragents plan execute + ``` + +#### Issue: Plan Execution Fails with Decision Error + +**Error Message:** +``` +DecisionError: Failed to make decision at node 'analyze_requirements' +StrategyError: No valid strategy found +``` + +**Causes:** +- Decision tree incomplete +- No valid strategy for current state +- Missing decision context +- Conflicting constraints + +**Solutions:** + +1. **Check decision tree:** + ```bash + cleveragents plan show-decisions + ``` + +2. **Review decision context:** + ```bash + cleveragents plan show-context + ``` + +3. **Check available strategies:** + ```bash + cleveragents plan list-strategies + ``` + +4. **Enable decision tracing:** + ```bash + export CLEVERAGENTS_TRACE_DECISIONS=true + cleveragents plan execute + ``` + +5. **Review logs for decision details:** + ```bash + grep -i "decision\|strategy" ~/.cleveragents/logs/cleveragents.log + ``` + +### Tool and Skill Issues + +#### Issue: Tool Execution Failed + +**Error Message:** +``` +ToolExecutionError: Tool 'git_clone' failed with exit code 1 +ToolError: Tool not found or not accessible +``` + +**Causes:** +- Tool not installed +- Tool not in PATH +- Tool execution failed +- Insufficient permissions + +**Solutions:** + +1. **Check tool availability:** + ```bash + cleveragents tool list + cleveragents tool show + ``` + +2. **Verify tool is installed:** + ```bash + which git + which python + which docker + ``` + +3. **Check tool permissions:** + ```bash + ls -la $(which git) + ``` + +4. **Test tool directly:** + ```bash + git --version + python --version + docker --version + ``` + +5. **Check tool configuration:** + ```bash + cleveragents config show | grep -A10 "tools:" + ``` + +#### Issue: Skill Not Found + +**Error Message:** +``` +SkillNotFoundError: Skill 'analyze_code' not found +SkillLoadError: Failed to load skill from module +``` + +**Causes:** +- Skill not registered +- Skill module not found +- Skill configuration incorrect +- Import error in skill module + +**Solutions:** + +1. **List available skills:** + ```bash + cleveragents skill list + ``` + +2. **Check skill registration:** + ```bash + cleveragents skill show + ``` + +3. **Verify skill module:** + ```bash + python -c "from cleveragents.skills import analyze_code" + ``` + +4. **Check skill configuration:** + ```bash + cleveragents config show | grep -A10 "skills:" + ``` + +5. **Enable debug logging:** + ```bash + export CLEVERAGENTS_LOG_LEVEL=DEBUG + cleveragents skill list + ``` + +### Sandbox and Checkpoint Issues + +#### Issue: Sandbox Creation Failed + +**Error Message:** +``` +SandboxError: Failed to create sandbox +GitWorktreeError: Failed to create git worktree +``` + +**Causes:** +- Git repository not initialized +- Insufficient disk space +- Permission denied on repository +- Corrupted git state + +**Solutions:** + +1. **Check git repository:** + ```bash + git status + git rev-parse --git-dir + ``` + +2. **Verify disk space:** + ```bash + df -h + du -sh . + ``` + +3. **Check git worktrees:** + ```bash + git worktree list + ``` + +4. **Clean up old worktrees:** + ```bash + git worktree prune + ``` + +5. **Repair git repository:** + ```bash + git fsck --full + git gc --aggressive + ``` + +#### Issue: Checkpoint Restore Failed + +**Error Message:** +``` +CheckpointError: Failed to restore from checkpoint +StateRestorationError: Invalid checkpoint state +``` + +**Causes:** +- Checkpoint file corrupted +- Checkpoint version mismatch +- Missing checkpoint data +- Incompatible state format + +**Solutions:** + +1. **List available checkpoints:** + ```bash + cleveragents checkpoint list + ``` + +2. **Check checkpoint details:** + ```bash + cleveragents checkpoint show + ``` + +3. **Verify checkpoint integrity:** + ```bash + cleveragents checkpoint validate + ``` + +4. **Delete corrupted checkpoint:** + ```bash + cleveragents checkpoint delete + ``` + +5. **Create new checkpoint:** + ```bash + cleveragents checkpoint create --description "Recovery checkpoint" + ``` + +## Diagnostic Procedures and Tools + +### Gathering Debug Information + +#### Enable Debug Logging + +```bash +# Set log level to DEBUG +export CLEVERAGENTS_LOG_LEVEL=DEBUG + +# Or in configuration +cleveragents config set logging.level DEBUG + +# Run command with debug output +cleveragents plan execute +``` + +#### Collect System Information + +```bash +# Create diagnostic bundle +cleveragents diag collect + +# Or manually gather information +echo "=== System Info ===" > diag.txt +uname -a >> diag.txt +python --version >> diag.txt +pip list >> diag.txt + +echo "=== CleverAgents Info ===" >> diag.txt +cleveragents --version >> diag.txt +cleveragents config show >> diag.txt + +echo "=== Environment ===" >> diag.txt +env | grep CLEVERAGENTS >> diag.txt +``` + +#### Enable Profiling + +```bash +# CPU profiling +export CLEVERAGENTS_PROFILE_CPU=true + +# Memory profiling +export CLEVERAGENTS_PROFILE_MEMORY=true + +# Both +export CLEVERAGENTS_PROFILE=true + +# Run command +cleveragents plan execute + +# View results +cleveragents diag show-profile +``` + +#### Enable Tracing + +```bash +# Enable all tracing +export CLEVERAGENTS_TRACE=true + +# Trace specific components +export CLEVERAGENTS_TRACE_DECISIONS=true +export CLEVERAGENTS_TRACE_TOOLS=true +export CLEVERAGENTS_TRACE_SKILLS=true + +# Run command +cleveragents plan execute +``` + +### Log Analysis Guide + +#### Log File Locations + +```bash +# Main application log +~/.cleveragents/logs/cleveragents.log + +# API server log +~/.cleveragents/logs/server.log + +# Agent execution log +~/.cleveragents/logs/agent-.log + +# Plan execution log +~/.cleveragents/logs/plan-.log +``` + +#### Viewing Logs + +```bash +# View recent logs +tail -f ~/.cleveragents/logs/cleveragents.log + +# View last N lines +tail -n 100 ~/.cleveragents/logs/cleveragents.log + +# Search for errors +grep -i "error\|exception\|failed" ~/.cleveragents/logs/cleveragents.log + +# Search with context +grep -B5 -A5 "error" ~/.cleveragents/logs/cleveragents.log + +# Filter by timestamp +grep "2024-04-19" ~/.cleveragents/logs/cleveragents.log + +# Follow specific component +grep "DecisionEngine" ~/.cleveragents/logs/cleveragents.log +``` + +#### Analyzing Log Patterns + +```bash +# Count errors by type +grep -i "error" ~/.cleveragents/logs/cleveragents.log | cut -d: -f3 | sort | uniq -c + +# Find slowest operations +grep "duration=" ~/.cleveragents/logs/cleveragents.log | sort -t= -k2 -nr | head -10 + +# Identify resource bottlenecks +grep -i "memory\|cpu\|disk" ~/.cleveragents/logs/cleveragents.log + +# Track execution flow +grep "step\|phase\|stage" ~/.cleveragents/logs/cleveragents.log +``` + +#### Log Format + +CleverAgents logs follow this format: + +``` +[TIMESTAMP] [LEVEL] [COMPONENT] [CONTEXT] MESSAGE +``` + +Example: +``` +[2024-04-19T10:30:45.123Z] [ERROR] [DecisionEngine] [plan:01HXM8C2ZK4Q7C2B3F2R4VYV6J] Failed to make decision: No valid strategy found +``` + +### Performance Diagnostics + +#### Check System Resources + +```bash +# CPU usage +top -b -n 1 | head -20 + +# Memory usage +free -h + +# Disk usage +df -h + +# Network connections +netstat -tuln | grep LISTEN +``` + +#### Profile Execution + +```bash +# Generate CPU profile +cleveragents plan execute --profile-cpu + +# Generate memory profile +cleveragents plan execute --profile-memory + +# View profile results +cleveragents diag show-profile --type cpu +cleveragents diag show-profile --type memory +``` + +#### Benchmark Operations + +```bash +# Run performance benchmark +cleveragents benchmark run + +# Compare with baseline +cleveragents benchmark compare --baseline baseline.json + +# Generate report +cleveragents benchmark report --output report.html +``` + +## Error Message Reference + +### Common Error Messages and Solutions + +#### ConfigurationError + +| Message | Cause | Solution | +|---------|-------|----------| +| `Configuration file not found` | Config file missing | Run `cleveragents config init` | +| `Invalid YAML syntax` | YAML parsing error | Validate YAML, check indentation | +| `Missing required field` | Required config value absent | Set missing value in config or env var | +| `Invalid value for field` | Config value invalid | Check value type and constraints | + +#### ExecutionError + +| Message | Cause | Solution | +|---------|-------|----------| +| `Execution timeout` | Operation took too long | Increase timeout, optimize plan | +| `Execution failed` | Unspecified execution error | Check logs, enable debug mode | +| `Invalid plan` | Plan configuration invalid | Validate plan, check constraints | +| `Plan not found` | Plan doesn't exist | List plans, verify plan ID | + +#### ToolError + +| Message | Cause | Solution | +|---------|-------|----------| +| `Tool not found` | Tool not registered | Install tool, check PATH | +| `Tool execution failed` | Tool returned error | Check tool logs, verify inputs | +| `Tool timeout` | Tool took too long | Increase timeout, optimize tool | +| `Tool permission denied` | Insufficient permissions | Check file/directory permissions | + +#### SkillError + +| Message | Cause | Solution | +|---------|-------|----------| +| `Skill not found` | Skill not registered | Register skill, check module | +| `Skill load failed` | Error loading skill module | Check imports, enable debug logging | +| `Skill execution failed` | Skill returned error | Check skill logs, verify inputs | +| `Skill timeout` | Skill took too long | Increase timeout, optimize skill | + +#### DecisionError + +| Message | Cause | Solution | +|---------|-------|----------| +| `No valid strategy` | No strategy matches state | Review decision tree, add strategy | +| `Decision tree invalid` | Decision tree malformed | Validate decision tree structure | +| `Context missing` | Required context not available | Provide missing context | +| `Constraint violation` | Constraint violated | Review constraints, adjust plan | + +### Error Code Reference + +| Code | Meaning | Action | +|------|---------|--------| +| 1 | General error | Check logs for details | +| 2 | Configuration error | Verify configuration | +| 3 | Execution error | Check plan and inputs | +| 4 | Tool error | Verify tool availability | +| 5 | Skill error | Check skill registration | +| 6 | Decision error | Review decision tree | +| 7 | Sandbox error | Check git repository | +| 8 | Checkpoint error | Verify checkpoint state | +| 127 | Command not found | Install missing tool | +| 255 | Unknown error | Enable debug logging | + +## Gathering Debug Information + +### Creating a Diagnostic Bundle + +```bash +# Automatic diagnostic collection +cleveragents diag collect --output diag-bundle.tar.gz + +# Manual collection +mkdir -p diag-report +cp ~/.cleveragents/config.yaml diag-report/ +cp ~/.cleveragents/logs/*.log diag-report/ +cleveragents --version > diag-report/version.txt +python --version >> diag-report/version.txt +pip list > diag-report/packages.txt +env | grep CLEVERAGENTS > diag-report/environment.txt +tar -czf diag-report.tar.gz diag-report/ +``` + +### Enabling Verbose Output + +```bash +# Verbose mode +cleveragents plan execute --verbose + +# Very verbose (debug) +cleveragents plan execute --debug + +# JSON output for parsing +cleveragents plan execute --output json +``` + +### Capturing Network Traffic + +```bash +# Using tcpdump +sudo tcpdump -i lo -w cleveragents.pcap port 8000 + +# Using mitmproxy +mitmproxy -p 8001 --mode reverse:http://localhost:8000 + +# Using curl with verbose +curl -v http://localhost:8000/health +``` + +### Reproducing Issues + +```bash +# Minimal reproduction script +cat > reproduce_issue.sh << 'EOF' +#!/bin/bash +set -x # Enable debug output + +# Set up environment +export CLEVERAGENTS_LOG_LEVEL=DEBUG +export CLEVERAGENTS_TRACE=true + +# Run command that fails +cleveragents plan execute + +# Capture output +EOF + +chmod +x reproduce_issue.sh +./reproduce_issue.sh 2>&1 | tee reproduction.log +``` + +## When and How to Seek Support + +### Before Seeking Support + +Complete this checklist before opening an issue: + +- [ ] Verified Python version is 3.10+ +- [ ] Virtual environment is activated +- [ ] CleverAgents is installed: `cleveragents --version` +- [ ] Configuration is valid: `cleveragents config validate` +- [ ] Searched existing issues for similar problem +- [ ] Reproduced issue with minimal example +- [ ] Collected debug information (see above) +- [ ] Checked logs for error messages +- [ ] Tried suggested solutions from this guide + +### Creating an Issue Report + +When reporting an issue, include: + +1. **Environment Information:** + ``` + - OS: [e.g., Ubuntu 22.04] + - Python: [e.g., 3.11.0] + - CleverAgents: [e.g., 3.6.0] + - Installation method: [e.g., pip, source] + ``` + +2. **Steps to Reproduce:** + ``` + 1. [First step] + 2. [Second step] + 3. [etc.] + ``` + +3. **Expected Behavior:** + ``` + [What should happen] + ``` + +4. **Actual Behavior:** + ``` + [What actually happens] + ``` + +5. **Error Output:** + ``` + [Full error message and traceback] + ``` + +6. **Logs:** + ``` + [Relevant log excerpts] + ``` + +7. **Diagnostic Information:** + - Output of `cleveragents --version` + - Output of `python --version` + - Output of `cleveragents config show` + - Diagnostic bundle (if available) + +### Support Channels + +| Channel | Use For | Response Time | +|---------|---------|----------------| +| **GitHub Issues** | Bug reports, feature requests | 24-48 hours | +| **GitHub Discussions** | Questions, best practices | 24-48 hours | +| **Email** | Urgent issues, security concerns | 4-8 hours | +| **Slack** | Real-time discussion, quick questions | 1-2 hours | + +### Reporting Security Issues + +**Do not open public issues for security vulnerabilities.** + +Instead: +1. Email security@cleverthis.com with details +2. Include steps to reproduce +3. Allow 90 days for patch before public disclosure +4. Do not share vulnerability details publicly + +## FAQ for Operational Issues + +### Q: How do I update CleverAgents? + +**A:** Use pip to upgrade: +```bash +pip install --upgrade cleveragents +``` + +Or with development dependencies: +```bash +pip install --upgrade -e ".[dev]" +``` + +### Q: How do I uninstall CleverAgents? + +**A:** Use pip to uninstall: +```bash +pip uninstall cleveragents +``` + +Or remove the entire virtual environment: +```bash +deactivate +rm -rf venv +``` + +### Q: How do I reset my configuration? + +**A:** Backup and reinitialize: +```bash +# Backup current config +cp ~/.cleveragents/config.yaml ~/.cleveragents/config.yaml.backup + +# Reset to defaults +rm ~/.cleveragents/config.yaml +cleveragents config init +``` + +### Q: How do I clear the cache? + +**A:** Clear various caches: +```bash +# Clear pip cache +pip cache purge + +# Clear CleverAgents cache +rm -rf ~/.cleveragents/cache + +# Clear database +rm ~/.cleveragents/cleveragents.db +cleveragents db init +``` + +### Q: How do I run CleverAgents in production? + +**A:** Use the server mode: +```bash +# Start server +cleveragents server --host 0.0.0.0 --port 8000 --workers 4 + +# Or use Docker +docker run -d -p 8000:8000 cleveragents:latest +``` + +### Q: How do I monitor CleverAgents? + +**A:** Enable monitoring: +```bash +# Enable metrics +export CLEVERAGENTS_METRICS_ENABLED=true + +# View metrics +curl http://localhost:8000/metrics + +# Enable tracing +export CLEVERAGENTS_TRACE=true +``` + +### Q: How do I backup my data? + +**A:** Backup configuration and database: +```bash +# Backup everything +tar -czf cleveragents-backup.tar.gz ~/.cleveragents/ + +# Backup just database +cp ~/.cleveragents/cleveragents.db ~/cleveragents.db.backup +``` + +### Q: How do I restore from backup? + +**A:** Restore from backup: +```bash +# Restore everything +tar -xzf cleveragents-backup.tar.gz -C ~/ + +# Restore just database +cp ~/cleveragents.db.backup ~/.cleveragents/cleveragents.db +``` + +### Q: How do I migrate to a new machine? + +**A:** Transfer configuration and data: +```bash +# On old machine +tar -czf cleveragents-migration.tar.gz ~/.cleveragents/ + +# Transfer file to new machine +scp cleveragents-migration.tar.gz user@newhost:~/ + +# On new machine +tar -xzf cleveragents-migration.tar.gz -C ~/ +``` + +### Q: How do I run tests? + +**A:** Run the test suite: +```bash +# All tests +nox + +# Specific test suite +nox -s unit_tests +nox -s integration_tests + +# With coverage +nox -s coverage_report +``` + +### Q: How do I contribute to CleverAgents? + +**A:** Follow the contribution guidelines: +1. Read [CONTRIBUTING.md](../../CONTRIBUTING.md) +2. Fork the repository +3. Create a feature branch +4. Make changes and add tests +5. Submit a pull request + +## Additional Resources + +- **Documentation:** https://docs.cleverthis.com/cleveragents +- **GitHub Repository:** https://github.com/cleverthis/cleveragents-core +- **Issue Tracker:** https://github.com/cleverthis/cleveragents-core/issues +- **Discussions:** https://github.com/cleverthis/cleveragents-core/discussions +- **Email Support:** support@cleverthis.com +- **Architecture Guide:** [Architecture](../architecture.md) +- **API Reference:** [API Documentation](../api/index.md) +- **FAQ:** [FAQ](../faq.md) +- **Installation Guide:** [Installation and Setup](./installation-setup.md) diff --git a/src/cleveragents/a2a/events.py b/src/cleveragents/a2a/events.py index f17ae21e7..cfbd7bba4 100644 --- a/src/cleveragents/a2a/events.py +++ b/src/cleveragents/a2a/events.py @@ -305,10 +305,17 @@ class EventBusBridge: data=dict(details) if details else {}, ) - import contextlib - - with contextlib.suppress(RuntimeError): + try: self._event_queue.publish(a2a_event) + except RuntimeError as e: + # Only suppress the specific error when the queue is closed. + # Other RuntimeErrors should propagate. + if "Cannot publish to a closed event queue" not in str(e): + raise + logger.debug( + "a2a.event_bridge.queue_closed", + event_type=sse_type, + ) __all__ = [