feat: Multi-backend support with fallback chain

Backend priority:
1. OpenRouter (OPENROUTER_API_KEY) - cloud LLMs, best quality
2. Agent Zero API (AGENTZERO_API_URL) - self-hosted instance
3. Local Deterministic - pattern matching, works offline

New backends:
- llm_providers/agentzero.py - connects to self-hosted Agent Zero
- llm_providers/local.py - rule-based, no LLM required

Security note:
All backends go through the same security flow:
  User Input -> Backend -> tool_request -> ToolApprovalScreen -> execute

The security interceptor is NOT bypassed regardless of backend choice.

Tests: 36 passed

Author: vizi2000

.env.example

@@ -1,14 +1,39 @@
-# OpenRouter API Key (required)
-# Get yours at: https://openrouter.ai/keys
-OPENROUTER_API_KEY=sk-or-v1-xxx
+# Agent Zero CLI Configuration
+# Copy to .env and fill in your values
 
-# Default model (optional)
-# Options: anthropic/claude-3-sonnet, openai/gpt-4-turbo, meta-llama/llama-3-70b
-OPENROUTER_MODEL=anthropic/claude-3-sonnet
+# ============================================
+# BACKEND PRIORITY (uses first available):
+# 1. OpenRouter (cloud LLMs)
+# 2. Agent Zero API (self-hosted)
+# 3. Local mode (no LLM, pattern matching)
+# ============================================
 
-# Security mode (optional)
-# Options: paranoid, balanced, god_mode
+# --- Option 1: OpenRouter (recommended for best quality) ---
+# Get API key at: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=sk-or-v1-xxx
+
+# Optional: specify models for load balancing (comma-separated)
+# OPENROUTER_MODELS=mistralai/devstral-2512:free,qwen/qwen3-coder:free
+
+# --- Option 2: Self-hosted Agent Zero ---
+# URL to your Agent Zero instance
+# AGENTZERO_API_URL=http://localhost:50001/api_message
+# AGENTZERO_API_KEY=your-api-key-if-required
+
+# --- Option 3: Local mode ---
+# No configuration needed - works offline with pattern matching
+# Limited functionality but no API required
+
+# ============================================
+# SECURITY SETTINGS
+# ============================================
+
+# Security mode: paranoid | balanced | god_mode
 AGENT_SECURITY_MODE=balanced
 
-# Debug mode (optional)
+# ============================================
+# DEBUG
+# ============================================
+
+# Enable debug logging
 AGENT_DEBUG=false

backend.py

@@ -1,90 +1,103 @@
 """
 Backend factory for AgentZeroCLI
-Auto-detects available backends (OpenRouter or Mock)
-"""
-import os
-import asyncio
-
-
-class MockAgentBackend:
-    """
-    Mock backend for offline/demo mode.
-    Used when OPENROUTER_API_KEY is not set.
-    """
-
-    async def send_prompt(self, user_text: str):
-        """Simulate sending prompt and receiving stream of thoughts."""
-        
-        yield {"type": "status", "content": "[MOCK MODE] Simulating response..."}
-        await asyncio.sleep(0.3)
-        
-        yield {"type": "thought", "content": f"Processing: '{user_text}'"}
-        await asyncio.sleep(0.5)
 
-        thoughts = [
-            "Analyzing project structure...",
-            "Found relevant files.",
-            "Preparing response..."
-        ]
+Priority order:
+1. OpenRouter (if OPENROUTER_API_KEY set) - best quality, cloud LLMs
+2. Agent Zero API (if AGENTZERO_API_URL set) - self-hosted Agent Zero
+3. Local Deterministic (always available) - pattern matching, no LLM
 
-        for thought in thoughts:
-            yield {"type": "thought", "content": thought}
-            await asyncio.sleep(0.4)
+All backends go through the same security flow:
+  User Input → Backend → tool_request → ToolApprovalScreen → execute
+"""
 
-        # Simulate tool request
-        yield {
-            "type": "tool_request",
-            "tool_name": "shell",
-            "command": "ls -la",
-            "reason": "List files to understand project structure.",
-            "risk_level": "low"
-        }
+import os
+from typing import Protocol, AsyncGenerator, Any
 
-    async def explain_risk(self, command: str):
-        """Simulate risk explanation."""
-        await asyncio.sleep(0.5)
-        return (
-            f"[MOCK] Command: {command}\n"
-            f"Risk Level: LOW\n"
-            f"This is a simulated analysis."
-        )
 
-    async def execute_tool(self, tool_name: str = "shell", command: str = "", cwd: str | None = None):
-        """Execute tool (real execution even in mock mode)."""
-        from tools.executor import execute_tool as real_execute
-        
-        async for event in real_execute(tool_name, command, cwd):
-            yield event
+class BackendProtocol(Protocol):
+    """Protocol for all backends."""
+    
+    async def send_prompt(self, user_text: str) -> AsyncGenerator[Any, None]: ...
+    async def explain_risk(self, command: str) -> str: ...
+    async def execute_tool(self, tool_name: str, command: str, cwd: str | None = None) -> AsyncGenerator[Any, None]: ...
+    async def close(self) -> None: ...
 
 
-def get_backend():
+def get_backend() -> BackendProtocol:
     """
-    Factory function to get the appropriate backend.
-    Returns OpenRouterBackend if API key is set, otherwise MockAgentBackend.
+    Factory function to get the best available backend.
+    
+    Priority:
+    1. OpenRouter (cloud LLMs) - if OPENROUTER_API_KEY is set
+    2. Agent Zero API (self-hosted) - if AGENTZERO_API_URL is set
+    3. Local Deterministic - always available, pattern matching
+    
+    All tool_requests go through ToolApprovalScreen regardless of backend.
     """
     from dotenv import load_dotenv
     load_dotenv()
 
-    api_key = os.getenv("OPENROUTER_API_KEY")
-    
-    if api_key:
+    # Priority 1: OpenRouter (best quality, multiple models)
+    openrouter_key = os.getenv("OPENROUTER_API_KEY")
+    if openrouter_key:
         try:
             from llm_providers.openrouter import OpenRouterBackend
-            backend = OpenRouterBackend(api_key=api_key)
-            print(f"[green]✓[/green] OpenRouter connected ({len(backend.models)} models)")
+            backend = OpenRouterBackend(api_key=openrouter_key)
+            print(f"[OK] OpenRouter connected ({len(backend.models)} models)")
             return backend
         except ImportError as e:
-            print(f"[yellow]⚠[/yellow] OpenRouter import failed: {e}")
-            print("[yellow]⚠[/yellow] Falling back to mock backend")
-            return MockAgentBackend()
+            print(f"[WARN] OpenRouter import failed: {e}")
         except Exception as e:
-            print(f"[yellow]⚠[/yellow] OpenRouter init failed: {e}")
-            return MockAgentBackend()
-    else:
-        print("[yellow]⚠[/yellow] No API key - using mock backend")
-        print("[dim]Set OPENROUTER_API_KEY in .env for real AI[/dim]")
-        return MockAgentBackend()
+            print(f"[WARN] OpenRouter init failed: {e}")
+    
+    # Priority 2: Agent Zero API (self-hosted)
+    agentzero_url = os.getenv("AGENTZERO_API_URL")
+    if agentzero_url:
+        try:
+            from llm_providers.agentzero import AgentZeroBackend
+            backend = AgentZeroBackend(api_url=agentzero_url)
+            print(f"[OK] Agent Zero connected ({agentzero_url})")
+            return backend
+        except ImportError as e:
+            print(f"[WARN] AgentZero import failed: {e}")
+        except Exception as e:
+            print(f"[WARN] AgentZero init failed: {e}")
+    
+    # Priority 3: Local deterministic (always works)
+    try:
+        from llm_providers.local import LocalBackend
+        backend = LocalBackend()
+        print("[OK] Local mode (pattern matching, no LLM)")
+        print("[INFO] For AI responses, set OPENROUTER_API_KEY or AGENTZERO_API_URL")
+        return backend
+    except ImportError:
+        pass
+    
+    # Fallback: Minimal mock (should never reach here)
+    print("[WARN] No backend available, using minimal mock")
+    return MinimalMockBackend()
+
+
+class MinimalMockBackend:
+    """Absolute minimal fallback - should never be used in practice."""
+    
+    async def send_prompt(self, user_text: str):
+        yield {
+            "type": "final_response", 
+            "content": "No backend configured. Set OPENROUTER_API_KEY or AGENTZERO_API_URL in .env"
+        }
+    
+    async def explain_risk(self, command: str) -> str:
+        return f"Cannot analyze '{command}' - no backend configured."
+    
+    async def execute_tool(self, tool_name: str = "shell", command: str = "", cwd: str | None = None):
+        from tools.executor import execute_tool as real_execute
+        async for event in real_execute(tool_name, command, cwd):
+            yield event
+    
+    async def close(self):
+        pass
 
 
-# For backwards compatibility
-__all__ = ["MockAgentBackend", "get_backend"]
+# Backwards compatibility
+__all__ = ["get_backend", "BackendProtocol"]