Document --continue mode

Signed-off-by: Víctor Mayoral Vilches <v.mayoralv@gmail.com>

docs/cai_quickstart.md

@@ -36,6 +36,28 @@ That should initialize CAI and provide a prompt to execute any security task you
 
 Here's a quick [demo video](https://asciinema.org/a/zm7wS5DA2o0S9pu1Tb44pnlvy) to help you get started with CAI. We'll walk through the basic steps — from launching the tool to running your first AI-powered task in the terminal. Whether you're a beginner or just curious, this guide will show you how easy it is to begin using CAI.
 
+### Autonomous Mode with --continue
+
+CAI can run autonomously using the `--continue` flag, which makes agents automatically continue their work without waiting for user input:
+
+```bash
+# Have CAI tell security jokes continuously
+cai --continue --prompt "tell me a joke about security"
+
+# Run autonomous security audit
+cai --continue --prompt "perform security audit of authentication system"
+
+# Hunt for vulnerabilities automatically
+cai --continue --prompt "find SQL injection vulnerabilities"
+```
+
+With `--continue`, CAI will:
+- Analyze the conversation context after each turn
+- Generate intelligent continuation prompts
+- Keep working until the task is complete or interrupted
+
+See the [Continue Mode Guide](continue_mode.md) for detailed information.
+
 From here on, type on `CAI` and start your security exercise. Best way to learn is by example:
 
 ### Environment Variables

docs/continue_mode.md

@@ -0,0 +1,332 @@
+# CAI Continue Mode
+
+## Overview
+
+The `--continue` flag enables CAI agents to operate autonomously by automatically generating intelligent continuation prompts when they would normally stop and wait for user input. This feature uses AI-powered analysis to provide contextual advice based on the conversation history, allowing agents to work on complex tasks without manual intervention.
+
+## Quick Start
+
+```bash
+# Tell jokes continuously
+cai --continue --prompt "tell me a joke about security"
+
+# Analyze code autonomously  
+cai --continue --prompt "find all SQL injection vulnerabilities in this codebase"
+
+# Run security audit
+cai --continue --prompt "perform a comprehensive security audit"
+```
+
+## Example: Security Jokes with Continue Mode
+
+Here's what happens when you run `cai --continue --prompt "tell me a joke about security"`:
+
+```bash
+$ cai --continue --prompt "tell me a joke about security"
+
+🤖 Processing initial prompt: tell me a joke about security
+
+Agent: Why did the hacker break up with their password? 
+       Because it wasn't strong enough! 💔🔐
+
+🤖 Auto-continuing with: Tell another cybersecurity joke or pun.
+
+Agent: Why don't cybersecurity experts tell secrets at parties?
+       Because they're afraid of social engineering! 🎉🕵️
+
+🤖 Auto-continuing with: Tell another cybersecurity joke or pun.
+
+Agent: What's a hacker's favorite season?
+       Phishing season! 🎣💻
+
+[Continues until interrupted with Ctrl+C]
+```
+
+## How It Works
+
+### 1. Intelligent Context Analysis
+
+When an agent completes a turn, the continuation system analyzes:
+- **Original request**: The initial task or prompt from the user
+- **Conversation history**: Recent messages and responses
+- **Tool usage**: Which tools were used and their outputs
+- **Error states**: Any errors encountered and their types
+- **Task progress**: Current state of task completion
+
+### 2. AI-Powered Continuation Generation
+
+The system uses the configured AI model (default: alias1) to generate contextual continuation prompts:
+
+```python
+# The system creates a detailed context summary
+context_summary = """
+ORIGINAL TASK: Tell me a joke about security
+CONVERSATION FLOW:
+User: Tell me a joke about security
+Agent: Why did the hacker break up with their password? Because it wasn't strong enough!
+
+CURRENT STATUS:
+- Last action: Told a cybersecurity joke
+- Tools used: None
+- Errors: No
+
+Generate a specific continuation prompt...
+"""
+```
+
+### 3. Smart Fallback System
+
+When the AI model is unavailable, the system provides intelligent fallbacks based on context:
+
+| Scenario | Fallback Continuation |
+|----------|----------------------|
+| Security joke told | "Tell another cybersecurity joke or pun." |
+| File not found | "Search for the correct file path or create the missing resource." |
+| Search completed | "Examine the search results in detail and investigate the most relevant findings." |
+| Security analysis | "Analyze the code for security vulnerabilities like injection flaws or authentication issues." |
+| Permission denied | "Check permissions and try accessing the resource with appropriate credentials." |
+
+## Common Use Cases
+
+### 1. Automated Security Audits
+```bash
+cai --continue --prompt "perform a security audit of the authentication system"
+```
+The agent will:
+- Search for authentication-related files
+- Analyze code for vulnerabilities
+- Check for common security issues
+- Generate a comprehensive report
+
+### 2. Continuous Bug Hunting
+```bash
+cai --continue --prompt "find and document all XSS vulnerabilities"
+```
+The agent will:
+- Search for user input handling code
+- Identify potential XSS vectors
+- Document findings
+- Suggest fixes
+
+### 3. Extended Code Analysis
+```bash
+cai --continue --prompt "analyze this codebase for OWASP Top 10 vulnerabilities"
+```
+The agent will:
+- Systematically check for each vulnerability type
+- Provide detailed findings
+- Continue until all categories are covered
+
+### 4. Entertainment Mode
+```bash
+cai --continue --prompt "tell me cybersecurity jokes and fun facts"
+```
+The agent will:
+- Tell jokes about security topics
+- Share interesting security facts
+- Continue entertaining until stopped
+
+## Configuration
+
+### Environment Variables
+
+```bash
+# Use a different model for continuation generation
+export CAI_MODEL=gpt-4
+cai --continue --prompt "analyze this code"
+
+# Set a fallback model if primary fails
+export CAI_CONTINUATION_FALLBACK_MODEL=gpt-3.5-turbo
+cai --continue --prompt "test application security"
+
+# Configure API keys for custom models
+export ALIAS_API_KEY=your-api-key
+cai --continue --prompt "perform penetration testing"
+```
+
+### Combining with Other CAI Features
+
+```bash
+# Use specific agent with continue mode
+CAI_AGENT_TYPE=bug_bounter_agent cai --continue --prompt "test example.com"
+
+# Set workspace for file operations
+CAI_WORKSPACE=project1 cai --continue --prompt "audit all Python files"
+
+# Enable streaming for real-time output
+CAI_STREAM=true cai --continue --prompt "monitor security events"
+```
+
+## Advanced Features
+
+### Continuation Decision Logic
+
+The system decides whether to continue based on:
+1. **Completion indicators**: Stops if agent says "completed", "finished", "done"
+2. **Active work detection**: Continues if tools are being used
+3. **Error recovery**: Attempts to resolve errors automatically
+4. **Task progress**: Evaluates if the original goal is achieved
+
+### Context-Aware Prompts
+
+The continuation prompts adapt based on:
+- **Task type**: Security analysis, testing, code review, etc.
+- **Current state**: Errors, findings, progress
+- **Tool usage**: Different prompts for different tools
+- **Conversation flow**: Maintains coherent task progression
+
+## Best Practices
+
+### 1. Clear Initial Prompts
+```bash
+# Good - Specific and actionable
+cai --continue --prompt "find SQL injection vulnerabilities in user.py"
+
+# Less effective - Too vague
+cai --continue --prompt "check security"
+```
+
+### 2. Monitor Progress
+- Check output periodically to ensure correct direction
+- Use Ctrl+C to stop if needed
+- Review logs for detailed execution history
+
+### 3. Set Appropriate Limits
+```python
+# In code integration, use max_turns
+run_cai_cli(
+    starting_agent=agent,
+    initial_prompt="analyze security",
+    continue_mode=True,
+    max_turns=10  # Limit to 10 turns
+)
+```
+
+### 4. Error Handling
+The system automatically:
+- Retries failed operations with different approaches
+- Searches for alternatives when files are missing
+- Adjusts strategies based on error types
+
+## Troubleshooting
+
+### Issue: Generic Continuation Messages
+**Symptom**: Always see "Continue working on the task based on your previous findings"
+
+**Solution**: 
+- Check model configuration is correct
+- Ensure API keys are valid
+- Review debug logs for API errors
+
+### Issue: Continuation Not Triggering
+**Symptom**: Agent stops after completing a task
+
+**Possible causes**:
+- Agent explicitly said task is "completed" or "done"
+- No recent tool usage detected
+- Error in continuation module
+
+**Solution**:
+- Use more open-ended initial prompts
+- Check logs for completion indicators
+- Verify --continue flag is properly set
+
+### Issue: Infinite Loops
+**Symptom**: Agent keeps doing the same thing
+
+**Solution**:
+- Set max_turns limit
+- Use more specific initial prompts
+- Interrupt with Ctrl+C and refine the task
+
+## Technical Implementation
+
+### Core Components
+
+1. **`src/cai/continuation.py`**: Main continuation logic
+   - `generate_continuation_advice()`: Creates AI-powered prompts
+   - `should_continue_automatically()`: Decides when to continue
+
+2. **`src/cai/cli.py`**: Integration point
+   - `--continue` flag handling
+   - Continuation loop implementation
+
+3. **Context Analysis**: 
+   - Extracts conversation history
+   - Identifies tool usage patterns
+   - Detects error conditions
+
+### API Integration
+
+The continuation system uses LiteLLM for model calls:
+```python
+response = await litellm.acompletion(
+    model=model_name,
+    messages=[{"role": "user", "content": context_summary}],
+    temperature=0.3,  # Low temperature for focused responses
+    max_tokens=150
+)
+```
+
+## Examples Gallery
+
+### Security Audit Continuation
+```
+Original: "Audit the login system"
+→ "Search for authentication-related files in the codebase."
+→ "Analyze the login function for SQL injection vulnerabilities."
+→ "Check password hashing implementation for security best practices."
+→ "Review session management for potential security issues."
+```
+
+### Bug Bounty Continuation
+```
+Original: "Test example.com for vulnerabilities"
+→ "Perform initial reconnaissance to gather information about the target."
+→ "Scan for exposed endpoints and services."
+→ "Test authentication endpoints for common vulnerabilities."
+→ "Check for information disclosure in error messages."
+```
+
+### Code Review Continuation
+```
+Original: "Review api.py for security issues"
+→ "Analyze input validation in API endpoints."
+→ "Check for proper authentication and authorization."
+→ "Review error handling for information leakage."
+→ "Examine data serialization for injection vulnerabilities."
+```
+
+## Example Scripts
+
+Explore working examples in the `examples/` directory:
+
+### Security Jokes Example
+```python
+# examples/continue_mode_jokes.py
+# Demonstrates continuous joke telling with --continue flag
+python examples/continue_mode_jokes.py
+```
+
+### Security Audit Example
+```python
+# examples/continue_mode_security_audit.py
+# Shows autonomous vulnerability scanning with --continue
+python examples/continue_mode_security_audit.py
+```
+
+These examples demonstrate:
+- How to use --continue flag programmatically
+- Handling continuous output
+- Graceful interruption with Ctrl+C
+- Practical security use cases
+
+## Summary
+
+The `--continue` flag transforms CAI into an autonomous cybersecurity assistant capable of:
+- Working independently on complex tasks
+- Recovering from errors intelligently
+- Maintaining context across multiple operations
+- Providing entertainment with continuous jokes
+
+Whether you're conducting security audits, hunting for bugs, or just want some cybersecurity humor, continue mode keeps your agent working until the job is done.

examples/continue_mode_jokes.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python3
+"""
+Example: Using CAI Continue Mode for Security Jokes
+
+This example demonstrates how to use CAI's --continue flag to have an agent
+continuously tell cybersecurity jokes without manual intervention.
+
+Usage:
+    python examples/continue_mode_jokes.py
+    
+Or directly from command line:
+    cai --continue --prompt "tell me a joke about security"
+"""
+
+import subprocess
+import sys
+import os
+import signal
+
+def run_joke_session():
+    """Run CAI with continue mode to tell security jokes"""
+    
+    print("🎭 CAI Security Joke Session")
+    print("=" * 60)
+    print("Starting CAI in continue mode to tell cybersecurity jokes...")
+    print("Press Ctrl+C to stop when you've had enough laughs!")
+    print("=" * 60)
+    
+    # Command to run CAI with continue flag
+    cmd = [
+        sys.executable, 
+        "src/cai/cli.py",
+        "--continue",
+        "--prompt", "tell me a joke about cybersecurity"
+    ]
+    
+    try:
+        # Run CAI
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.PIPE,
+            text=True,
+            bufsize=1
+        )
+        
+        # Close stdin to prevent hanging
+        proc.stdin.close()
+        
+        # Read and display output
+        for line in proc.stdout:
+            print(line, end='')
+            
+            # Highlight continuation messages
+            if "Auto-continuing with:" in line:
+                print("🔄 " + "=" * 56)
+                
+    except KeyboardInterrupt:
+        print("\n\n✋ Joke session interrupted by user")
+        if proc.poll() is None:
+            proc.terminate()
+            print("   Gracefully stopping CAI...")
+            
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        
+    print("\n" + "=" * 60)
+    print("Thanks for using CAI joke mode! 🎉")
+
+if __name__ == "__main__":
+    # Change to project root directory
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(script_dir)
+    os.chdir(project_root)
+    
+    run_joke_session()

examples/continue_mode_security_audit.py

@@ -0,0 +1,137 @@
+#!/usr/bin/env python3
+"""
+Example: Autonomous Security Audit with CAI Continue Mode
+
+This example shows how to use CAI's --continue flag to perform an autonomous
+security audit that continues analyzing files and finding vulnerabilities
+without manual intervention.
+
+Usage:
+    python examples/continue_mode_security_audit.py
+    
+Or directly from command line:
+    cai --continue --prompt "perform a security audit of all Python files"
+"""
+
+import subprocess
+import sys
+import os
+import time
+import signal
+
+def run_security_audit():
+    """Run CAI with continue mode for autonomous security auditing"""
+    
+    print("🔒 CAI Autonomous Security Audit")
+    print("=" * 60)
+    print("Starting autonomous security audit...")
+    print("CAI will continuously analyze code for vulnerabilities.")
+    print("Press Ctrl+C to stop the audit.")
+    print("=" * 60)
+    
+    # Create a sample vulnerable file for demonstration
+    sample_file = "sample_vulnerable.py"
+    with open(sample_file, "w") as f:
+        f.write('''
+# Sample file with security vulnerabilities for CAI to find
+
+import os
+import sqlite3
+
+def login(username, password):
+    # SQL Injection vulnerability
+    conn = sqlite3.connect('users.db')
+    query = f"SELECT * FROM users WHERE name='{username}' AND pass='{password}'"
+    cursor = conn.execute(query)
+    return cursor.fetchone()
+
+def execute_command(user_input):
+    # Command Injection vulnerability
+    os.system(f"echo {user_input}")
+    
+def read_file(filename):
+    # Path Traversal vulnerability
+    with open(f"/app/data/{filename}", "r") as f:
+        return f.read()
+
+# Hardcoded credentials
+API_KEY = "sk-1234567890abcdef"
+DB_PASSWORD = "admin123"
+''')
+    
+    # Command to run CAI audit
+    cmd = [
+        sys.executable, 
+        "src/cai/cli.py",
+        "--continue",
+        "--prompt", f"Perform a comprehensive security audit of {sample_file}, "
+                   f"identify all vulnerabilities, and suggest fixes"
+    ]
+    
+    try:
+        # Run CAI
+        proc = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            stdin=subprocess.PIPE,
+            text=True,
+            bufsize=1
+        )
+        
+        # Close stdin
+        proc.stdin.close()
+        
+        # Track findings
+        vulnerabilities_found = []
+        continuation_count = 0
+        
+        # Read output
+        for line in proc.stdout:
+            print(line, end='')
+            
+            # Track vulnerabilities
+            vuln_keywords = ["injection", "vulnerability", "security issue", 
+                           "hardcoded", "insecure", "exposed"]
+            if any(keyword in line.lower() for keyword in vuln_keywords):
+                vulnerabilities_found.append(line.strip())
+            
+            # Track continuations
+            if "Auto-continuing with:" in line:
+                continuation_count += 1
+                print(f"🔄 Continuation #{continuation_count} " + "=" * 40)
+                
+                # Stop after finding multiple issues
+                if continuation_count >= 5:
+                    print("\n📋 Audit Summary: Found multiple security issues.")
+                    print("   Stopping audit after thorough analysis.")
+                    proc.terminate()
+                    break
+                    
+    except KeyboardInterrupt:
+        print("\n\n✋ Security audit interrupted by user")
+        if proc and proc.poll() is None:
+            proc.terminate()
+            
+    except Exception as e:
+        print(f"\n❌ Error: {e}")
+        
+    finally:
+        # Cleanup
+        if os.path.exists(sample_file):
+            os.remove(sample_file)
+            print(f"\n🗑️  Cleaned up {sample_file}")
+    
+    print("\n" + "=" * 60)
+    print("🔒 Security Audit Complete")
+    if vulnerabilities_found:
+        print(f"   Found {len(set(vulnerabilities_found))} potential security issues")
+    print("=" * 60)
+
+if __name__ == "__main__":
+    # Change to project root directory
+    script_dir = os.path.dirname(os.path.abspath(__file__))
+    project_root = os.path.dirname(script_dir)
+    os.chdir(project_root)
+    
+    run_security_audit()

mkdocs.yml

@@ -93,6 +93,7 @@ nav:
   # ========================================
   - Guides:
       - Running Agents: running_agents.md
+      - Continue Mode: continue_mode.md
       - Working with Results: results.md
       - Streaming: streaming.md
       - Tracing & Debugging: tracing.md