feat: v4.0 Real Execution Engine - TerminalEngine, FilesystemEngine, GitHubEngine, SelfRepairEngine, DeploymentEngine, AutonomousAgent

agents/autonomous_agent.py

@@ -0,0 +1,365 @@
+"""
+AutonomousAgent — Devin/Manus-style Execution-First Agent v4.0
+NOT a chatbot. NOT a prompt wrapper.
+A REAL autonomous coding operator that:
+1. Plans task graph (DAG)
+2. Executes via real terminal + filesystem
+3. Self-repairs on errors (up to 3 retries)
+4. Commits to GitHub
+5. Deploys to Vercel/HuggingFace
+6. Verifies deployment
+7. Returns live URLs + repo links
+"""
+
+import asyncio
+import json
+import os
+import re
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+import structlog
+
+from .base_agent import BaseAgent
+from tools.real_executor import RealToolRouter, get_tool_router
+
+log = structlog.get_logger()
+
+WORKSPACE = os.environ.get("WORKSPACE_DIR", "/tmp/god_workspace")
+GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
+
+AUTONOMOUS_SYSTEM = """You are GOD AGENT — an elite autonomous software engineer like Devin + Manus combined.
+
+You EXECUTE, not just advise.
+You CODE, not just describe.
+You DEPLOY, not just plan.
+
+YOUR MISSION CONTROL PROCESS:
+1. Analyze the goal deeply
+2. Create a concrete execution plan (task graph)
+3. Execute each step using real tools
+4. Self-repair on failures
+5. Verify results
+6. Report live URLs
+
+AVAILABLE TOOLS (use tool_call JSON format):
+- terminal.run: {"command": "bash command"}
+- terminal.sequence: {"commands": ["cmd1", "cmd2"]}
+- terminal.run_with_repair: {"command": "cmd", "related_files": ["file.py"]}
+- fs.read: {"path": "filename"}
+- fs.write: {"path": "filename", "content": "..."}
+- fs.patch: {"path": "file", "old": "old text", "new": "new text"}
+- fs.tree: {}
+- fs.list: {"path": "dir"}
+- fs.search: {"query": "text", "pattern": "*.py"}
+- github.clone: {"url": "https://github.com/..."}
+- github.create_repo: {"name": "repo-name", "description": "..."}
+- github.commit_push: {"repo_path": "/path", "message": "feat: ...", "branch": "main"}
+- github.create_pr: {"owner": "user", "repo": "name", "title": "...", "body": "...", "head": "branch"}
+- deploy.vercel: {"dir": "/path", "name": "project"}
+- deploy.hf: {"repo_path": "/path", "space_name": "user/space"}
+- workspace.info: {}
+
+RESPOND IN THIS FORMAT:
+{
+  "thinking": "brief analysis",
+  "plan": ["step 1", "step 2", ...],
+  "tool_call": {"tool": "tool.name", "params": {...}},
+  "result_summary": "what was accomplished"
+}
+
+For multi-step tasks, respond with one tool_call at a time.
+After each tool result, continue with the next step.
+"""
+
+
+class AutonomousAgent(BaseAgent):
+    """
+    Execution-first autonomous agent.
+    Uses real tool router for actual file/terminal/github operations.
+    """
+
+    def __init__(self, ws_manager=None, ai_router=None):
+        super().__init__("AutonomousAgent", ws_manager, ai_router)
+        self.tool_router: Optional[RealToolRouter] = None
+
+    def _get_router(self) -> RealToolRouter:
+        if not self.tool_router:
+            self.tool_router = get_tool_router(
+                ws_manager=self.ws,
+                ai_router=self.ai_router,
+            )
+        return self.tool_router
+
+    async def run(self, task: str, context: Dict = {}, **kwargs) -> str:
+        session_id = kwargs.get("session_id", "")
+        task_id = kwargs.get("task_id", "")
+        max_steps = kwargs.get("max_steps", 20)
+
+        await self.emit(task_id, "autonomous_start", {
+            "agent": "AutonomousAgent",
+            "task": task[:100],
+            "max_steps": max_steps,
+        }, session_id)
+
+        router = self._get_router()
+        results_history = []
+        all_artifacts = []
+
+        # Initial planning pass
+        plan = await self._create_execution_plan(task, context, task_id=task_id, session_id=session_id)
+
+        await self.emit(task_id, "plan_ready", {
+            "agent": "AutonomousAgent",
+            "plan": plan,
+            "steps": len(plan),
+        }, session_id)
+
+        step_num = 0
+        conversation = []
+
+        # Build initial messages
+        conversation.append({
+            "role": "system",
+            "content": AUTONOMOUS_SYSTEM,
+        })
+        conversation.append({
+            "role": "user",
+            "content": (
+                f"GOAL: {task}\n\n"
+                f"EXECUTION PLAN:\n" + "\n".join(f"{i+1}. {s}" for i, s in enumerate(plan)) + "\n\n"
+                f"Context: {json.dumps(context)[:500]}\n\n"
+                f"Workspace: {WORKSPACE}\n\n"
+                f"Start execution. Respond with the first tool_call JSON."
+            ),
+        })
+
+        while step_num < max_steps:
+            step_num += 1
+
+            await self.emit(task_id, "step_start", {
+                "step": step_num,
+                "max_steps": max_steps,
+            }, session_id)
+
+            # Get next action from LLM
+            raw_response = await self.llm(
+                conversation,
+                task_id=task_id,
+                session_id=session_id,
+                temperature=0.1,
+                max_tokens=4096,
+            )
+
+            # Parse tool call
+            tool_call = self._parse_tool_call(raw_response)
+
+            if not tool_call:
+                # No more tool calls — task complete
+                await self.emit(task_id, "autonomous_complete", {
+                    "steps": step_num,
+                    "artifacts": all_artifacts,
+                    "summary": raw_response[:500],
+                }, session_id)
+                results_history.append({"step": step_num, "result": raw_response})
+                break
+
+            tool = tool_call.get("tool", "")
+            params = tool_call.get("params", {})
+            thinking = tool_call.get("thinking", "")
+
+            if thinking:
+                await self.emit(task_id, "agent_thinking", {
+                    "thought": thinking[:200],
+                    "step": step_num,
+                }, session_id)
+
+            await self.emit(task_id, "tool_calling", {
+                "tool": tool,
+                "step": step_num,
+                "params_preview": str(params)[:100],
+            }, session_id)
+
+            # Execute the tool
+            tool_result = await router.route(
+                tool=tool,
+                params=params,
+                session_id=session_id,
+                task_id=task_id,
+            )
+
+            # Track artifacts
+            if tool == "deploy.vercel" and tool_result.get("url"):
+                all_artifacts.append({
+                    "type": "deployment",
+                    "platform": "vercel",
+                    "url": tool_result["url"],
+                })
+            elif tool == "deploy.hf" and tool_result.get("url"):
+                all_artifacts.append({
+                    "type": "deployment",
+                    "platform": "huggingface",
+                    "url": tool_result["url"],
+                })
+            elif tool == "github.create_repo" and tool_result.get("url"):
+                all_artifacts.append({
+                    "type": "repository",
+                    "url": tool_result["url"],
+                    "name": tool_result.get("name", ""),
+                })
+            elif tool == "fs.write" and tool_result.get("success"):
+                all_artifacts.append({
+                    "type": "file",
+                    "path": tool_result.get("path", ""),
+                    "lines": tool_result.get("lines", 0),
+                })
+
+            results_history.append({
+                "step": step_num,
+                "tool": tool,
+                "params": params,
+                "result": tool_result,
+            })
+
+            # Add result to conversation
+            conversation.append({
+                "role": "assistant",
+                "content": raw_response,
+            })
+            conversation.append({
+                "role": "user",
+                "content": (
+                    f"Tool result for {tool}:\n"
+                    f"Success: {tool_result.get('success', 'N/A')}\n"
+                    f"Output: {json.dumps(tool_result)[:1500]}\n\n"
+                    f"Artifacts so far: {json.dumps(all_artifacts)[:500]}\n\n"
+                    + ("Continue with next step. Respond with next tool_call JSON, or if DONE respond with a final summary (no tool_call)." if step_num < max_steps else "Provide final summary.")
+                ),
+            })
+
+            # Keep conversation manageable
+            if len(conversation) > 30:
+                # Keep system + first user + last 20
+                conversation = conversation[:2] + conversation[-20:]
+
+        # Build final output
+        return self._build_final_output(task, results_history, all_artifacts, step_num)
+
+    async def _create_execution_plan(
+        self,
+        task: str,
+        context: Dict,
+        task_id: str = "",
+        session_id: str = "",
+    ) -> List[str]:
+        """Generate a concrete execution plan."""
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are an expert software architect. Create a concrete execution plan.\n"
+                    "Return ONLY a JSON array of strings, no explanation.\n"
+                    "Each step must be a concrete ACTION (not vague).\n"
+                    'Example: ["Create project directory", "Write main.py with FastAPI routes", "Install dependencies", "Run tests", "Deploy to Vercel"]\n'
+                    "Max 10 steps."
+                ),
+            },
+            {
+                "role": "user",
+                "content": f"Task: {task}\nContext: {json.dumps(context)[:300]}",
+            },
+        ]
+
+        raw = await self.llm(messages, task_id=task_id, session_id=session_id, temperature=0.2, max_tokens=500)
+
+        try:
+            start = raw.find("[")
+            end = raw.rfind("]") + 1
+            if start >= 0 and end > start:
+                plan = json.loads(raw[start:end])
+                if isinstance(plan, list):
+                    return [str(s) for s in plan[:10]]
+        except Exception:
+            pass
+
+        # Fallback plan
+        return [
+            "Analyze requirements",
+            "Set up project structure",
+            "Write core implementation",
+            "Add error handling",
+            "Test functionality",
+            "Package and deploy",
+        ]
+
+    def _parse_tool_call(self, raw: str) -> Optional[Dict]:
+        """Parse tool_call JSON from LLM response."""
+        # Try to find JSON block
+        patterns = [
+            r'```json\s*(\{.*?\})\s*```',
+            r'```\s*(\{.*?\})\s*```',
+            r'(\{[^{}]*"tool_call"[^{}]*\{.*?\}.*?\})',
+        ]
+
+        for pattern in patterns:
+            match = re.search(pattern, raw, re.DOTALL)
+            if match:
+                try:
+                    data = json.loads(match.group(1))
+                    if "tool_call" in data:
+                        tc = data["tool_call"]
+                        tc["thinking"] = data.get("thinking", "")
+                        return tc
+                    return data
+                except Exception:
+                    pass
+
+        # Try direct JSON parse
+        try:
+            start = raw.find("{")
+            end = raw.rfind("}") + 1
+            if start >= 0 and end > start:
+                data = json.loads(raw[start:end])
+                if "tool_call" in data:
+                    tc = data["tool_call"]
+                    tc["thinking"] = data.get("thinking", "")
+                    return tc
+                if "tool" in data:
+                    return data
+        except Exception:
+            pass
+
+        return None
+
+    def _build_final_output(
+        self,
+        task: str,
+        results: List[Dict],
+        artifacts: List[Dict],
+        steps: int,
+    ) -> str:
+        """Build a comprehensive final output."""
+        lines = [f"## ✅ Task Complete: {task[:80]}\n"]
+        lines.append(f"**Steps executed:** {steps}")
+
+        if artifacts:
+            lines.append("\n### 🎯 Artifacts\n")
+            for a in artifacts:
+                if a["type"] == "deployment":
+                    lines.append(f"- 🌐 **{a['platform'].title()} Deploy:** [{a['url']}]({a['url']})")
+                elif a["type"] == "repository":
+                    lines.append(f"- 📦 **GitHub Repo:** [{a.get('name', a['url'])}]({a['url']})")
+                elif a["type"] == "file":
+                    lines.append(f"- 📄 **File:** `{a['path']}` ({a.get('lines', 0)} lines)")
+
+        # Show key steps
+        lines.append("\n### 📋 Execution Log\n")
+        for r in results[-8:]:
+            tool = r.get("tool", "thinking")
+            result = r.get("result", {})
+            success = result.get("success", True) if isinstance(result, dict) else True
+            icon = "✅" if success else "❌"
+            lines.append(f"{icon} Step {r['step']}: `{tool}`")
+
+        return "\n".join(lines)

api/routes/execution.py

@@ -0,0 +1,415 @@
+"""
+Real Execution API Routes — v4.0
+Exposes the real tool router, filesystem, terminal, GitHub, deployment
+"""
+
+import asyncio
+import json
+import os
+import time
+import uuid
+from typing import Any, Dict, List, Optional
+
+import structlog
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import StreamingResponse
+from pydantic import BaseModel
+
+log = structlog.get_logger()
+
+router = APIRouter()
+
+WORKSPACE = os.environ.get("WORKSPACE_DIR", "/tmp/god_workspace")
+
+
+# ─── Request Models ─────────────────────────────────────────────────────────
+
+class ToolCallRequest(BaseModel):
+    tool: str
+    params: Dict[str, Any] = {}
+    session_id: str = ""
+    task_id: str = ""
+
+
+class TerminalRequest(BaseModel):
+    command: str
+    session_id: str = ""
+    task_id: str = ""
+    cwd: Optional[str] = None
+    timeout: int = 60
+
+
+class FileWriteRequest(BaseModel):
+    path: str
+    content: str
+    session_id: str = ""
+    task_id: str = ""
+
+
+class FilePatchRequest(BaseModel):
+    path: str
+    old_content: str
+    new_content: str
+    session_id: str = ""
+    task_id: str = ""
+
+
+class GitHubCloneRequest(BaseModel):
+    url: str
+    target: str = ""
+    session_id: str = ""
+    task_id: str = ""
+
+
+class GitHubCreateRepoRequest(BaseModel):
+    name: str
+    description: str = ""
+    private: bool = False
+    session_id: str = ""
+    task_id: str = ""
+
+
+class GitHubCommitRequest(BaseModel):
+    repo_path: str = WORKSPACE
+    message: str = "God Agent automated commit"
+    branch: str = "main"
+    session_id: str = ""
+    task_id: str = ""
+
+
+class GitHubPRRequest(BaseModel):
+    owner: str
+    repo: str
+    title: str
+    body: str = ""
+    head: str = "main"
+    base: str = "main"
+    session_id: str = ""
+    task_id: str = ""
+
+
+class DeployVercelRequest(BaseModel):
+    project_dir: str = WORKSPACE
+    project_name: str = "god-agent-app"
+    session_id: str = ""
+    task_id: str = ""
+
+
+class DeployHFRequest(BaseModel):
+    repo_path: str = WORKSPACE
+    space_name: str = ""
+    session_id: str = ""
+    task_id: str = ""
+
+
+class AutonomousTaskRequest(BaseModel):
+    goal: str
+    context: Dict[str, Any] = {}
+    session_id: str = ""
+    task_id: str = ""
+    max_steps: int = 20
+
+
+# ─── Helper to get router ────────────────────────────────────────────────────
+
+def _get_tool_router(request: Request):
+    ws = getattr(request.app.state, "ws_manager", None)
+    ai_router = getattr(request.app.state, "ai_router", None)
+    from tools.real_executor import get_tool_router
+    return get_tool_router(ws_manager=ws, ai_router=ai_router)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# UNIFIED TOOL ROUTER ENDPOINT
+# ═══════════════════════════════════════════════════════════════════
+
+@router.post("/tool/call")
+async def call_tool(body: ToolCallRequest, request: Request):
+    """
+    Universal tool call endpoint.
+    Supports all tools: terminal, filesystem, github, deploy.
+    """
+    router_inst = _get_tool_router(request)
+    result = await router_inst.route(
+        tool=body.tool,
+        params=body.params,
+        session_id=body.session_id,
+        task_id=body.task_id,
+    )
+    return result
+
+
+# ═══════════════════════════════════════════════════════════════════
+# TERMINAL ENDPOINTS
+# ═══════════════════════════════════════════════════════════════════
+
+@router.post("/terminal/execute")
+async def terminal_execute(body: TerminalRequest, request: Request):
+    """Execute a shell command in the workspace."""
+    r = _get_tool_router(request)
+    result = await r.terminal.execute(
+        command=body.command,
+        session_id=body.session_id,
+        task_id=body.task_id,
+        cwd=body.cwd,
+        timeout=body.timeout,
+    )
+    return result
+
+
+@router.get("/terminal/workspace")
+async def get_workspace(request: Request):
+    """Get workspace information and file tree."""
+    r = _get_tool_router(request)
+    tree = await r.filesystem.tree()
+    info = await r.terminal.execute("df -h /tmp | tail -1 && free -h | grep Mem")
+    return {
+        "workspace": WORKSPACE,
+        "files": tree.get("files", []),
+        "file_count": tree.get("count", 0),
+        "system_info": info.get("output", ""),
+    }
+
+
+# ═══════════════════════════════════════════════════════════════════
+# FILESYSTEM ENDPOINTS
+# ═══════════════════════════════════════════════════════════════════
+
+@router.get("/fs/tree")
+async def fs_tree(request: Request, path: str = "", depth: int = 4):
+    r = _get_tool_router(request)
+    return await r.filesystem.tree(path, depth)
+
+
+@router.get("/fs/list")
+async def fs_list(request: Request, path: str = ""):
+    r = _get_tool_router(request)
+    return await r.filesystem.list_dir(path)
+
+
+@router.get("/fs/read")
+async def fs_read(request: Request, path: str):
+    r = _get_tool_router(request)
+    return await r.filesystem.read_file(path)
+
+
+@router.post("/fs/write")
+async def fs_write(body: FileWriteRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.filesystem.write_file(
+        body.path, body.content,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.post("/fs/patch")
+async def fs_patch(body: FilePatchRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.filesystem.patch_file(
+        body.path, body.old_content, body.new_content,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.delete("/fs/delete")
+async def fs_delete(request: Request, path: str):
+    r = _get_tool_router(request)
+    return await r.filesystem.delete_file(path)
+
+
+@router.get("/fs/search")
+async def fs_search(request: Request, query: str, path: str = "", pattern: str = "*"):
+    r = _get_tool_router(request)
+    return await r.filesystem.search_files(query, path, pattern)
+
+
+# ═══════════════════════════════════════════════════════════════════
+# GITHUB ENDPOINTS
+# ═══════════════════════════════════════════════════════════════════
+
+@router.post("/github/clone")
+async def github_clone(body: GitHubCloneRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.github.clone_repo(
+        body.url, body.target,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.post("/github/create-repo")
+async def github_create_repo(body: GitHubCreateRepoRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.github.create_repo(
+        body.name, body.description, body.private,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.post("/github/commit-push")
+async def github_commit_push(body: GitHubCommitRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.github.commit_and_push(
+        body.repo_path, body.message, body.branch,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.post("/github/create-pr")
+async def github_create_pr(body: GitHubPRRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.github.create_pr(
+        body.owner, body.repo, body.title, body.body,
+        body.head, body.base,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.get("/github/user")
+async def github_user(request: Request):
+    r = _get_tool_router(request)
+    return await r.github.get_user()
+
+
+@router.get("/github/issues")
+async def github_issues(request: Request, owner: str, repo: str, state: str = "open"):
+    r = _get_tool_router(request)
+    issues = await r.github.read_issues(owner, repo, state)
+    return {"issues": issues, "count": len(issues)}
+
+
+# ═══════════════════════════════════════════════════════════════════
+# DEPLOYMENT ENDPOINTS
+# ═══════════════════════════════════════════════════════════════════
+
+@router.post("/deploy/vercel")
+async def deploy_vercel(body: DeployVercelRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.deployment.deploy_vercel(
+        body.project_dir, body.project_name,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+@router.post("/deploy/huggingface")
+async def deploy_hf(body: DeployHFRequest, request: Request):
+    r = _get_tool_router(request)
+    return await r.deployment.deploy_hf_space(
+        body.repo_path, body.space_name,
+        session_id=body.session_id, task_id=body.task_id
+    )
+
+
+# ══════════════════��════════════════════════════════════════════════
+# AUTONOMOUS TASK ENDPOINT
+# ═══════════════════════════════════════════════════════════════════
+
+@router.post("/autonomous/run")
+async def autonomous_run(body: AutonomousTaskRequest, request: Request):
+    """
+    Run a fully autonomous task.
+    The agent will plan, execute, self-repair, and deploy.
+    """
+    ws = getattr(request.app.state, "ws_manager", None)
+    ai_router = getattr(request.app.state, "ai_router", None)
+
+    from agents.autonomous_agent import AutonomousAgent
+    agent = AutonomousAgent(ws_manager=ws, ai_router=ai_router)
+
+    task_id = body.task_id or f"auto_{uuid.uuid4().hex[:8]}"
+
+    # Run in background and return task_id immediately
+    asyncio.create_task(
+        agent.run(
+            body.goal,
+            context=body.context,
+            session_id=body.session_id,
+            task_id=task_id,
+            max_steps=body.max_steps,
+        )
+    )
+
+    return {
+        "task_id": task_id,
+        "goal": body.goal,
+        "status": "executing",
+        "stream_url": f"/api/v1/tasks/{task_id}/stream",
+        "ws_url": f"/ws/tasks/{task_id}",
+    }
+
+
+@router.post("/autonomous/run-sync")
+async def autonomous_run_sync(body: AutonomousTaskRequest, request: Request):
+    """Run autonomous task synchronously (waits for completion)."""
+    ws = getattr(request.app.state, "ws_manager", None)
+    ai_router = getattr(request.app.state, "ai_router", None)
+
+    from agents.autonomous_agent import AutonomousAgent
+    agent = AutonomousAgent(ws_manager=ws, ai_router=ai_router)
+
+    task_id = body.task_id or f"auto_{uuid.uuid4().hex[:8]}"
+
+    result = await agent.run(
+        body.goal,
+        context=body.context,
+        session_id=body.session_id,
+        task_id=task_id,
+        max_steps=body.max_steps,
+    )
+
+    return {
+        "task_id": task_id,
+        "goal": body.goal,
+        "status": "complete",
+        "result": result,
+    }
+
+
+# ─── Tool capabilities info ──────────────────────────────────────────────────
+
+@router.get("/tools")
+async def list_tools():
+    """List all available real tools."""
+    return {
+        "tools": {
+            "terminal": {
+                "terminal.run": "Execute shell command",
+                "terminal.sequence": "Run command sequence",
+                "terminal.run_with_repair": "Run with auto self-repair on error",
+            },
+            "filesystem": {
+                "fs.read": "Read file content",
+                "fs.write": "Write/create file",
+                "fs.patch": "Patch specific section of file",
+                "fs.delete": "Delete file",
+                "fs.move": "Move/rename file",
+                "fs.search": "Search file contents",
+                "fs.tree": "Get file tree",
+                "fs.list": "List directory",
+            },
+            "github": {
+                "github.clone": "Clone repository",
+                "github.create_repo": "Create new repository",
+                "github.commit_push": "Commit and push changes",
+                "github.create_branch": "Create new branch",
+                "github.create_pr": "Open pull request",
+                "github.read_issues": "Read open issues",
+            },
+            "deployment": {
+                "deploy.vercel": "Deploy to Vercel",
+                "deploy.hf": "Deploy to HuggingFace Spaces",
+            },
+            "autonomous": {
+                "autonomous.run": "Run fully autonomous task (async)",
+                "autonomous.run-sync": "Run fully autonomous task (sync)",
+            },
+        },
+        "workspace": WORKSPACE,
+        "capabilities": [
+            "Real terminal execution with streaming",
+            "File system read/write/patch/delete",
+            "GitHub clone/commit/push/PR creation",
+            "Self-repair loop (3 retries with AI analysis)",
+            "Vercel + HuggingFace deployment",
+            "Autonomous multi-step task execution",
+        ],
+    }

main.py

@@ -1,7 +1,7 @@
 """
-🚀 GOD MODE+ V5 — Manus · Genspark · Devin
-Autonomous AI Operating System — Production-Grade Backend
-Version: 5.0.0
+🚀 GOD MODE+ Autonomous AI Operating System
+Devin + Manus + Genspark Style — Production-Grade Backend
+Version: 4.0.0 — Real Execution Engine + Mission Control UI
 """
 
 import asyncio
@@ -24,12 +24,13 @@ from slowapi.errors import RateLimitExceeded
 
 from api.routes import tasks, chat, memory, github, health
 from api.routes import connectors, agents as agents_router
+from api.routes import execution as execution_router
 from api.websocket_manager import WebSocketManager
 from core.task_engine import TaskEngine
 from memory.db import init_db
 
-# ─── V5 AI Router ─────────────────────────────────────────────────────────────
-from ai_router.router_v5 import AIRouterV5
+# ─── God Mode Agents ───────────────────────────────────────────────────────────
+from ai_router.router import AIRouter
 from agents.orchestrator import GodAgentOrchestrator
 from agents.chat_agent import ChatAgent
 from agents.planner_agent import PlannerAgent
@@ -41,6 +42,7 @@ from agents.deploy_agent import DeployAgent
 from agents.workflow_agent import WorkflowAgent
 from agents.sandbox_agent import SandboxAgent
 from agents.ui_agent import UIAgent
+from agents.autonomous_agent import AutonomousAgent
 from connectors.manager import ConnectorManager
 
 # ─── Structured Logging ────────────────────────────────────────────────────────
@@ -60,13 +62,14 @@ limiter = Limiter(key_func=get_remote_address)
 # ─── Global Managers ──────────────────────────────────────────────────────────
 ws_manager = WebSocketManager()
 task_engine = TaskEngine(ws_manager)
-ai_router = AIRouterV5(ws_manager)
+ai_router = AIRouter(ws_manager)
 connector_manager = ConnectorManager()
 
-
 # ─── Build God Agent Ecosystem ────────────────────────────────────────────────
 def build_orchestrator() -> GodAgentOrchestrator:
     orchestrator = GodAgentOrchestrator(ws_manager=ws_manager, ai_router=ai_router)
+
+    # Register all specialized agents
     orchestrator.register_agent("chat",      ChatAgent(ws_manager, ai_router))
     orchestrator.register_agent("planner",   PlannerAgent(ws_manager, ai_router))
     orchestrator.register_agent("coding",    CodingAgent(ws_manager, ai_router))
@@ -77,33 +80,35 @@ def build_orchestrator() -> GodAgentOrchestrator:
     orchestrator.register_agent("workflow",  WorkflowAgent(ws_manager, ai_router))
     orchestrator.register_agent("sandbox",   SandboxAgent(ws_manager, ai_router))
     orchestrator.register_agent("ui",        UIAgent(ws_manager, ai_router))
-    log.info("🤖 God Agent Ecosystem V5 initialized", agents=10)
-    return orchestrator
+    orchestrator.register_agent("autonomous", AutonomousAgent(ws_manager, ai_router))
 
+    log.info("🤖 God Agent Ecosystem initialized", agents=10)
+    return orchestrator
 
 orchestrator = build_orchestrator()
 
 
 @asynccontextmanager
 async def lifespan(app: FastAPI):
-    log.info("🚀 Starting GOD MODE+ V5 AI Operating System...")
+    """Startup + Shutdown lifecycle."""
+    log.info("🚀 Starting GOD MODE+ AI Operating System...")
     await init_db()
     await task_engine.start()
     asyncio.create_task(ws_manager.heartbeat_loop())
-    providers = ai_router.get_provider_status()
-    active = [p for p, s in providers.items() if s.get("available")]
-    log.info("✅ GOD MODE+ V5 ready", active_providers=active)
+    log.info("✅ GOD MODE+ Platform ready — All agents online")
+    log.info("🤖 Agents: Chat, Planner, Coding, Debug, Memory, Connector, Deploy, Workflow, Sandbox, UI")
+    log.info("🌐 AI Router: OpenAI → Groq → Cerebras → OpenRouter → Anthropic")
     yield
-    log.info("🛑 Shutting down V5...")
+    log.info("🛑 Shutting down...")
     await task_engine.stop()
     log.info("✅ Shutdown complete")
 
 
 # ─── FastAPI App ───────────────────────────────────────────────────────────────
 app = FastAPI(
-    title="🤖 GOD MODE+ V5 — Manus · Genspark · Devin",
-    description="Autonomous AI Engineering Platform — Gemini · SambaNova · GitHub Models · OpenAI · Groq",
-    version="5.0.0",
+    title="🤖 GOD MODE+ AI Operating System",
+    description="Devin + Manus + Genspark Autonomous AI Engineering Platform",
+    version="3.0.0",
     lifespan=lifespan,
     docs_url="/api/docs",
     redoc_url="/api/redoc",
@@ -112,6 +117,7 @@ app = FastAPI(
 app.state.limiter = limiter
 app.add_exception_handler(RateLimitExceeded, _rate_limit_exceeded_handler)
 
+# ─── Share state ───────────────────────────────────────────────────────────────
 app.state.ws_manager = ws_manager
 app.state.task_engine = task_engine
 app.state.ai_router = ai_router
@@ -139,13 +145,40 @@ async def log_requests(request: Request, call_next):
 
 
 # ─── REST API Routers ──────────────────────────────────────────────────────────
-app.include_router(health.router,        prefix="/api/v1",            tags=["health"])
-app.include_router(tasks.router,         prefix="/api/v1/tasks",      tags=["tasks"])
-app.include_router(chat.router,          prefix="/api/v1",            tags=["chat"])
-app.include_router(memory.router,        prefix="/api/v1/memory",     tags=["memory"])
-app.include_router(github.router,        prefix="/api/v1/github",     tags=["github"])
-app.include_router(connectors.router,    prefix="/api/v1/connectors", tags=["connectors"])
-app.include_router(agents_router.router, prefix="/api/v1/agents",     tags=["agents"])
+app.include_router(health.router,             prefix="/api/v1",              tags=["health"])
+app.include_router(tasks.router,              prefix="/api/v1/tasks",        tags=["tasks"])
+app.include_router(chat.router,               prefix="/api/v1",              tags=["chat"])
+app.include_router(memory.router,             prefix="/api/v1/memory",       tags=["memory"])
+app.include_router(github.router,             prefix="/api/v1/github",       tags=["github"])
+app.include_router(connectors.router,         prefix="/api/v1/connectors",   tags=["connectors"])
+app.include_router(agents_router.router,      prefix="/api/v1/agents",       tags=["agents"])
+app.include_router(execution_router.router,   prefix="/api/v1/exec",         tags=["execution"])
+
+# ─── WebSocket: autonomous execution stream ────────────────────────────────
+@app.websocket("/ws/exec/{session_id}")
+async def ws_exec(websocket: WebSocket, session_id: str):
+    """Live execution streaming for autonomous tasks."""
+    await ws_manager.connect(websocket, room=f"exec:{session_id}")
+    try:
+        while True:
+            data = await websocket.receive_text()
+            msg = json.loads(data)
+            if msg.get("type") == "ping":
+                await websocket.send_json({"type": "pong", "timestamp": time.time()})
+            elif msg.get("type") == "run":
+                from agents.autonomous_agent import AutonomousAgent
+                agent = AutonomousAgent(ws_manager=ws_manager, ai_router=ai_router)
+                asyncio.create_task(
+                    agent.run(
+                        msg.get("goal", ""),
+                        context=msg.get("context", {}),
+                        session_id=session_id,
+                        task_id=session_id,
+                        max_steps=msg.get("max_steps", 20),
+                    )
+                )
+    except WebSocketDisconnect:
+        ws_manager.disconnect(websocket, room=f"exec:{session_id}")
 
 
 # ─── WebSocket Endpoints ───────────────────────────────────────────────────────
@@ -185,6 +218,7 @@ async def ws_chat(websocket: WebSocket, session_id: str):
             if msg.get("type") == "ping":
                 await websocket.send_json({"type": "pong", "timestamp": time.time()})
             elif msg.get("type") == "chat_message":
+                # Route through God Agent Orchestrator
                 asyncio.create_task(
                     orchestrator.orchestrate(
                         user_message=msg.get("content", ""),
@@ -193,8 +227,12 @@ async def ws_chat(websocket: WebSocket, session_id: str):
                     )
                 )
             elif msg.get("type") == "task_message":
+                # Create autonomous task via task engine
                 from core.models import TaskCreateRequest
-                req = TaskCreateRequest(goal=msg.get("content", ""), session_id=session_id)
+                req = TaskCreateRequest(
+                    goal=msg.get("content", ""),
+                    session_id=session_id,
+                )
                 asyncio.create_task(task_engine.submit(req))
     except WebSocketDisconnect:
         ws_manager.disconnect(websocket, room=f"chat:{session_id}")
@@ -210,14 +248,17 @@ async def ws_agent_status(websocket: WebSocket):
             if msg.get("type") == "ping":
                 await websocket.send_json({"type": "pong", "timestamp": time.time()})
             elif msg.get("type") == "get_status":
-                await websocket.send_json({"type": "agent_status", "data": orchestrator.get_status()})
+                await websocket.send_json({
+                    "type": "agent_status",
+                    "data": orchestrator.get_status(),
+                })
     except WebSocketDisconnect:
         ws_manager.disconnect(websocket, room="agent_status")
 
 
 @app.websocket("/ws/sandbox/{session_id}")
 async def ws_sandbox(websocket: WebSocket, session_id: str):
-    """Live sandbox terminal stream — V5 with timeout guard."""
+    """Live sandbox terminal stream."""
     await ws_manager.connect(websocket, room=f"sandbox:{session_id}")
     sandbox = orchestrator.get_agent("sandbox")
     try:
@@ -228,15 +269,7 @@ async def ws_sandbox(websocket: WebSocket, session_id: str):
                 await websocket.send_json({"type": "pong", "timestamp": time.time()})
             elif msg.get("type") == "execute" and sandbox:
                 cmd = msg.get("command", "")
-                try:
-                    result = await asyncio.wait_for(
-                        sandbox.execute(cmd, session_id=session_id),
-                        timeout=30.0
-                    )
-                except asyncio.TimeoutError:
-                    result = "⏱️ Command timed out after 30 seconds"
-                except Exception as e:
-                    result = f"❌ Error: {str(e)}"
+                result = await sandbox.execute(cmd, session_id=session_id)
                 await websocket.send_json({
                     "type": "terminal_output",
                     "command": cmd,
@@ -251,14 +284,11 @@ async def ws_sandbox(websocket: WebSocket, session_id: str):
 @app.get("/")
 async def root():
     cs = connector_manager.get_summary()
-    providers = ai_router.get_provider_status()
-    active_providers = [p for p, s in providers.items() if s.get("available")]
     return {
-        "name": "🤖 GOD MODE+ V5 — Manus · Genspark · Devin",
-        "version": "5.0.0",
+        "name": "🤖 GOD MODE+ AI Operating System",
+        "version": "3.0.0",
         "status": "operational",
-        "mode": "god_mode_plus_v5",
-        "ai_providers": active_providers,
+        "mode": "god_mode_plus",
         "agents": orchestrator.get_status()["agents"],
         "connectors": {
             "connected": cs["connected"],
@@ -266,4 +296,21 @@ async def root():
             "ai_ready": cs["ai_ready"],
         },
         "docs": "/api/docs",
+        "websockets": [
+            "/ws/tasks/{task_id}",
+            "/ws/logs",
+            "/ws/chat/{session_id}",
+            "/ws/agent/status",
+            "/ws/sandbox/{session_id}",
+        ],
+        "phases_complete": [
+            "Phase 1: God Agent Orchestrator",
+            "Phase 2: Sandbox Agent",
+            "Phase 3: Connector System",
+            "Phase 4: Autonomous Coding Engine",
+            "Phase 5: Memory System",
+            "Phase 6: Real-time Streaming",
+            "Phase 7: Workflow Factor OS",
+            "Phase 9: Multi-Model AI Router",
+        ],
     }

tools/real_executor.py

@@ -0,0 +1,1027 @@
+"""
+REAL EXECUTION ENGINE — God Mode+ v4.0
+Devin/Manus-style autonomous execution with:
+- Real terminal execution with streaming
+- File system control (read/write/patch/delete/move/search/tree)
+- GitHub autonomy (clone/commit/push/PR/branch)
+- Self-repair loop (error analysis + auto-patch + retry)
+- Deployment automation (Vercel/HuggingFace)
+- Tool call router
+"""
+
+import asyncio
+import json
+import os
+import re
+import subprocess
+import tempfile
+import time
+import uuid
+from pathlib import Path
+from typing import Any, Dict, List, Optional, Tuple
+
+import httpx
+import structlog
+
+log = structlog.get_logger()
+
+WORKSPACE = os.environ.get("WORKSPACE_DIR", "/tmp/god_workspace")
+GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
+HF_TOKEN = os.environ.get("HF_TOKEN", "")
+VERCEL_TOKEN = os.environ.get("VERCEL_TOKEN", "")
+
+os.makedirs(WORKSPACE, exist_ok=True)
+
+# ─── BLOCKED COMMANDS (Security) ────────────────────────────────────────────
+BLOCKED_PATTERNS = [
+    r"rm\s+-rf\s+/[^t]",  # rm -rf / but allow /tmp
+    r":\(\)\s*\{",         # fork bomb
+    r"mkfs\.",             # format filesystem
+    r"dd\s+if=/dev/",     # disk destruction
+    r"shutdown",
+    r"reboot",
+    r"halt",
+    r"poweroff",
+    r"chmod\s+777\s+/",
+    r"wget.*\|\s*bash",
+    r"curl.*\|\s*bash",
+]
+
+def is_blocked(cmd: str) -> bool:
+    for pattern in BLOCKED_PATTERNS:
+        if re.search(pattern, cmd, re.IGNORECASE):
+            return True
+    return False
+
+
+# ═══════════════════════════════════════════════════════════════════
+# TERMINAL EXECUTION ENGINE
+# ═══════════════════════════════════════════════════════════════════
+
+class TerminalEngine:
+    """Real shell execution with streaming output."""
+
+    def __init__(self, ws_manager=None):
+        self.ws = ws_manager
+        self._sessions: Dict[str, str] = {}  # session_id -> cwd
+
+    def get_cwd(self, session_id: str) -> str:
+        return self._sessions.get(session_id, WORKSPACE)
+
+    def set_cwd(self, session_id: str, cwd: str):
+        if os.path.isdir(cwd):
+            self._sessions[session_id] = cwd
+
+    async def execute(
+        self,
+        command: str,
+        session_id: str = "",
+        task_id: str = "",
+        cwd: Optional[str] = None,
+        timeout: int = 60,
+        env_vars: Dict[str, str] = {},
+    ) -> Dict[str, Any]:
+        """Execute command with real streaming output."""
+
+        if is_blocked(command):
+            return {
+                "success": False,
+                "output": f"❌ BLOCKED: Dangerous command rejected: {command[:80]}",
+                "exit_code": -1,
+                "command": command,
+            }
+
+        work_dir = cwd or self.get_cwd(session_id)
+        os.makedirs(work_dir, exist_ok=True)
+
+        # Handle cd specially
+        if command.strip().startswith("cd "):
+            new_dir = command.strip()[3:].strip()
+            if not os.path.isabs(new_dir):
+                new_dir = os.path.join(work_dir, new_dir)
+            new_dir = os.path.normpath(new_dir)
+            if os.path.isdir(new_dir):
+                self.set_cwd(session_id, new_dir)
+                return {"success": True, "output": f"📂 Changed to: {new_dir}", "exit_code": 0, "command": command, "cwd": new_dir}
+            else:
+                return {"success": False, "output": f"❌ Directory not found: {new_dir}", "exit_code": 1, "command": command}
+
+        # Build environment
+        env = {**os.environ, **env_vars}
+
+        # Emit start event
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "terminal_start", {
+                "command": command[:200],
+                "cwd": work_dir,
+                "session_id": session_id,
+            }, session_id=session_id)
+
+        output_lines = []
+        exit_code = 0
+
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                command,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                cwd=work_dir,
+                env=env,
+            )
+
+            # Stream output line by line
+            async def read_stream():
+                while True:
+                    try:
+                        line = await asyncio.wait_for(proc.stdout.readline(), timeout=timeout)
+                        if not line:
+                            break
+                        decoded = line.decode("utf-8", errors="replace").rstrip()
+                        output_lines.append(decoded)
+
+                        # Stream to websocket
+                        if self.ws and (task_id or session_id):
+                            await self.ws.emit(
+                                task_id or "logs",
+                                "terminal_output",
+                                {"line": decoded, "command": command[:80]},
+                                session_id=session_id,
+                            )
+                    except asyncio.TimeoutError:
+                        proc.kill()
+                        output_lines.append(f"\n⏱️ Command timed out after {timeout}s")
+                        break
+
+            await read_stream()
+            try:
+                exit_code = await asyncio.wait_for(proc.wait(), timeout=5)
+            except asyncio.TimeoutError:
+                proc.kill()
+                exit_code = -1
+
+        except Exception as e:
+            output_lines.append(f"❌ Execution error: {str(e)}")
+            exit_code = -1
+
+        full_output = "\n".join(output_lines)
+
+        # Emit completion
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "terminal_done", {
+                "command": command[:80],
+                "exit_code": exit_code,
+                "success": exit_code == 0,
+                "lines": len(output_lines),
+            }, session_id=session_id)
+
+        return {
+            "success": exit_code == 0,
+            "output": full_output[:8000],
+            "exit_code": exit_code,
+            "command": command,
+            "cwd": work_dir,
+        }
+
+    async def run_sequence(
+        self,
+        commands: List[str],
+        session_id: str = "",
+        task_id: str = "",
+        stop_on_error: bool = True,
+    ) -> List[Dict]:
+        """Run a sequence of commands, streaming each."""
+        results = []
+        for cmd in commands:
+            result = await self.execute(cmd, session_id=session_id, task_id=task_id)
+            results.append(result)
+            if not result["success"] and stop_on_error:
+                break
+        return results
+
+
+# ═══════════════════════════════════════════════════════════════════
+# FILESYSTEM CONTROL ENGINE
+# ═══════════════════════════════════════════════════════════════════
+
+class FilesystemEngine:
+    """Full file system control."""
+
+    def __init__(self, ws_manager=None):
+        self.ws = ws_manager
+
+    def _resolve(self, path: str, base: str = WORKSPACE) -> str:
+        if os.path.isabs(path):
+            resolved = os.path.normpath(path)
+        else:
+            resolved = os.path.normpath(os.path.join(base, path))
+        return resolved
+
+    async def read_file(self, path: str, session_id: str = "", task_id: str = "") -> Dict:
+        fpath = self._resolve(path)
+        try:
+            with open(fpath, "r", encoding="utf-8", errors="replace") as f:
+                content = f.read()
+            lines = content.split("\n")
+            result = {
+                "success": True,
+                "path": fpath,
+                "content": content,
+                "lines": len(lines),
+                "size": len(content),
+                "language": self._detect_language(fpath),
+            }
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "file_read", {"path": fpath, "lines": len(lines)}, session_id=session_id)
+            return result
+        except FileNotFoundError:
+            return {"success": False, "error": f"File not found: {path}"}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def write_file(self, path: str, content: str, session_id: str = "", task_id: str = "") -> Dict:
+        fpath = self._resolve(path)
+        os.makedirs(os.path.dirname(fpath), exist_ok=True)
+        try:
+            with open(fpath, "w", encoding="utf-8") as f:
+                f.write(content)
+            lines = len(content.split("\n"))
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "file_written", {
+                    "path": fpath,
+                    "filename": os.path.basename(fpath),
+                    "size": len(content),
+                    "lines": lines,
+                    "language": self._detect_language(fpath),
+                }, session_id=session_id)
+            return {"success": True, "path": fpath, "size": len(content), "lines": lines}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def patch_file(self, path: str, old_content: str, new_content: str, session_id: str = "", task_id: str = "") -> Dict:
+        """Patch a specific section of a file."""
+        fpath = self._resolve(path)
+        try:
+            with open(fpath, "r", encoding="utf-8") as f:
+                current = f.read()
+            if old_content not in current:
+                return {"success": False, "error": "Patch target not found in file"}
+            patched = current.replace(old_content, new_content, 1)
+            with open(fpath, "w", encoding="utf-8") as f:
+                f.write(patched)
+
+            # Emit diff event
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "file_patched", {
+                    "path": fpath,
+                    "filename": os.path.basename(fpath),
+                    "old_snippet": old_content[:100],
+                    "new_snippet": new_content[:100],
+                }, session_id=session_id)
+
+            return {
+                "success": True,
+                "path": fpath,
+                "diff": {
+                    "removed": old_content.split("\n")[:5],
+                    "added": new_content.split("\n")[:5],
+                }
+            }
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def delete_file(self, path: str, session_id: str = "", task_id: str = "") -> Dict:
+        fpath = self._resolve(path)
+        try:
+            os.remove(fpath)
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "file_deleted", {"path": fpath}, session_id=session_id)
+            return {"success": True, "path": fpath}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def move_file(self, src: str, dst: str, session_id: str = "", task_id: str = "") -> Dict:
+        import shutil
+        src_path = self._resolve(src)
+        dst_path = self._resolve(dst)
+        try:
+            os.makedirs(os.path.dirname(dst_path), exist_ok=True)
+            shutil.move(src_path, dst_path)
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "file_moved", {"from": src_path, "to": dst_path}, session_id=session_id)
+            return {"success": True, "from": src_path, "to": dst_path}
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def search_files(self, query: str, path: str = "", file_pattern: str = "*") -> Dict:
+        """Search file contents with grep."""
+        search_path = self._resolve(path) if path else WORKSPACE
+        try:
+            result = subprocess.run(
+                ["grep", "-r", "-l", "--include", file_pattern, query, search_path],
+                capture_output=True, text=True, timeout=10
+            )
+            files = [f for f in result.stdout.strip().split("\n") if f]
+            return {"success": True, "files": files, "count": len(files), "query": query}
+        except Exception as e:
+            return {"success": False, "error": str(e), "files": []}
+
+    async def tree(self, path: str = "", max_depth: int = 4) -> Dict:
+        """Get file tree of workspace."""
+        root = self._resolve(path) if path else WORKSPACE
+        try:
+            result = subprocess.run(
+                ["find", root, "-maxdepth", str(max_depth),
+                 "!", "-path", "*/node_modules/*",
+                 "!", "-path", "*/__pycache__/*",
+                 "!", "-path", "*/.git/*",
+                 "!", "-path", "*/.next/*",
+                 "-type", "f"],
+                capture_output=True, text=True, timeout=10
+            )
+            files = [os.path.relpath(f, root) for f in result.stdout.strip().split("\n") if f]
+            return {"success": True, "root": root, "files": files[:200], "count": len(files)}
+        except Exception as e:
+            return {"success": False, "error": str(e), "files": []}
+
+    async def list_dir(self, path: str = "") -> Dict:
+        target = self._resolve(path) if path else WORKSPACE
+        try:
+            entries = []
+            for item in sorted(os.listdir(target)):
+                full = os.path.join(target, item)
+                entries.append({
+                    "name": item,
+                    "type": "dir" if os.path.isdir(full) else "file",
+                    "size": os.path.getsize(full) if os.path.isfile(full) else 0,
+                })
+            return {"success": True, "path": target, "entries": entries}
+        except Exception as e:
+            return {"success": False, "error": str(e), "entries": []}
+
+    def _detect_language(self, path: str) -> str:
+        ext_map = {
+            ".py": "python", ".ts": "typescript", ".tsx": "tsx",
+            ".js": "javascript", ".jsx": "jsx", ".go": "go",
+            ".rs": "rust", ".java": "java", ".cpp": "cpp",
+            ".c": "c", ".sh": "bash", ".yaml": "yaml",
+            ".yml": "yaml", ".json": "json", ".md": "markdown",
+            ".html": "html", ".css": "css", ".sql": "sql",
+            ".dockerfile": "dockerfile", ".toml": "toml",
+        }
+        ext = Path(path).suffix.lower()
+        return ext_map.get(ext, "text")
+
+
+# ═══════════════════════════════════════════════════════════════════
+# GITHUB AUTONOMY ENGINE
+# ═���═════════════════════════════════════════════════════════════════
+
+class GitHubEngine:
+    """Full GitHub autonomy - clone, commit, push, PR, branch."""
+
+    def __init__(self, token: str = "", ws_manager=None):
+        self.token = token or GITHUB_TOKEN
+        self.ws = ws_manager
+        self.base_url = "https://api.github.com"
+        self.headers = {
+            "Authorization": f"token {self.token}",
+            "Accept": "application/vnd.github.v3+json",
+        }
+
+    async def _api(self, method: str, path: str, data: Dict = {}) -> Dict:
+        async with httpx.AsyncClient(timeout=30) as client:
+            url = f"{self.base_url}{path}"
+            if method == "GET":
+                r = await client.get(url, headers=self.headers)
+            elif method == "POST":
+                r = await client.post(url, json=data, headers=self.headers)
+            elif method == "PATCH":
+                r = await client.patch(url, json=data, headers=self.headers)
+            elif method == "PUT":
+                r = await client.put(url, json=data, headers=self.headers)
+            elif method == "DELETE":
+                r = await client.delete(url, headers=self.headers)
+            else:
+                return {"error": f"Unknown method: {method}"}
+            try:
+                return r.json()
+            except Exception:
+                return {"error": r.text, "status": r.status_code}
+
+    async def get_user(self) -> Dict:
+        return await self._api("GET", "/user")
+
+    async def clone_repo(
+        self,
+        repo_url: str,
+        target_dir: str = "",
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Clone a GitHub repository into workspace."""
+        if not target_dir:
+            repo_name = repo_url.rstrip("/").split("/")[-1].replace(".git", "")
+            target_dir = os.path.join(WORKSPACE, repo_name)
+
+        # Inject token into URL if available
+        if self.token and "github.com" in repo_url:
+            repo_url = repo_url.replace("https://", f"https://x-access-token:{self.token}@")
+
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "github_op", {
+                "op": "clone",
+                "repo": repo_url.split("@")[-1] if "@" in repo_url else repo_url,
+                "target": target_dir,
+            }, session_id=session_id)
+
+        try:
+            proc = await asyncio.create_subprocess_exec(
+                "git", "clone", "--depth", "50", repo_url, target_dir,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=120)
+            success = proc.returncode == 0
+            return {
+                "success": success,
+                "path": target_dir,
+                "output": (stdout or stderr).decode("utf-8", errors="replace")[:1000],
+            }
+        except Exception as e:
+            return {"success": False, "error": str(e)}
+
+    async def create_repo(
+        self,
+        name: str,
+        description: str = "",
+        private: bool = False,
+        auto_init: bool = True,
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Create a new GitHub repository."""
+        data = {
+            "name": name,
+            "description": description,
+            "private": private,
+            "auto_init": auto_init,
+        }
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "github_op", {"op": "create_repo", "name": name}, session_id=session_id)
+
+        result = await self._api("POST", "/user/repos", data)
+        return {
+            "success": "html_url" in result,
+            "url": result.get("html_url", ""),
+            "clone_url": result.get("clone_url", ""),
+            "ssh_url": result.get("ssh_url", ""),
+            "name": result.get("name", name),
+            "error": result.get("message", ""),
+        }
+
+    async def commit_and_push(
+        self,
+        repo_path: str,
+        message: str,
+        branch: str = "main",
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Stage all changes, commit, and push."""
+        commands = [
+            f"git -C {repo_path} add -A",
+            f'git -C {repo_path} commit -m "{message}" --allow-empty',
+            f"git -C {repo_path} push origin {branch} --force-with-lease 2>&1 || git -C {repo_path} push origin {branch}",
+        ]
+
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "github_op", {
+                "op": "commit_push",
+                "message": message,
+                "branch": branch,
+            }, session_id=session_id)
+
+        results = []
+        for cmd in commands:
+            proc = await asyncio.create_subprocess_shell(
+                cmd,
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.PIPE,
+                env={**os.environ, "GIT_TERMINAL_PROMPT": "0"},
+            )
+            stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=60)
+            out = (stdout or b"").decode("utf-8", errors="replace")
+            err = (stderr or b"").decode("utf-8", errors="replace")
+            results.append({
+                "cmd": cmd.split("'")[0][:60],
+                "success": proc.returncode == 0,
+                "output": (out + err)[:500],
+            })
+
+        return {
+            "success": all(r["success"] for r in results),
+            "steps": results,
+            "message": message,
+            "branch": branch,
+        }
+
+    async def create_branch(
+        self,
+        repo_path: str,
+        branch_name: str,
+        from_branch: str = "main",
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        cmd = f"git -C {repo_path} checkout -b {branch_name} origin/{from_branch} 2>/dev/null || git -C {repo_path} checkout -b {branch_name}"
+        proc = await asyncio.create_subprocess_shell(cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.PIPE)
+        stdout, stderr = await asyncio.wait_for(proc.communicate(), timeout=30)
+        return {"success": proc.returncode == 0, "branch": branch_name}
+
+    async def create_pr(
+        self,
+        owner: str,
+        repo: str,
+        title: str,
+        body: str,
+        head: str,
+        base: str = "main",
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Create a Pull Request."""
+        data = {"title": title, "body": body, "head": head, "base": base}
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "github_op", {"op": "create_pr", "title": title}, session_id=session_id)
+        result = await self._api("POST", f"/repos/{owner}/{repo}/pulls", data)
+        return {
+            "success": "html_url" in result,
+            "url": result.get("html_url", ""),
+            "number": result.get("number"),
+            "error": result.get("message", ""),
+        }
+
+    async def get_repo_contents(self, owner: str, repo: str, path: str = "") -> Dict:
+        result = await self._api("GET", f"/repos/{owner}/{repo}/contents/{path}")
+        return result
+
+    async def read_issues(self, owner: str, repo: str, state: str = "open") -> List[Dict]:
+        result = await self._api("GET", f"/repos/{owner}/{repo}/issues?state={state}&per_page=10")
+        if isinstance(result, list):
+            return [{"number": i.get("number"), "title": i.get("title"), "body": (i.get("body") or "")[:200]} for i in result]
+        return []
+
+
+# ═══════════════════════════════════════════════════════════════════
+# SELF-REPAIR LOOP ENGINE
+# ═══════════════════════════════════════════════════════════════════
+
+class SelfRepairEngine:
+    """
+    Devin-style self-repair loop:
+    Run → See error → Analyze → Patch → Retry → Pass
+    """
+
+    def __init__(self, terminal: TerminalEngine, filesystem: FilesystemEngine, ai_router=None, ws_manager=None):
+        self.terminal = terminal
+        self.filesystem = filesystem
+        self.ai_router = ai_router
+        self.ws = ws_manager
+
+    async def run_with_repair(
+        self,
+        command: str,
+        related_files: List[str] = [],
+        session_id: str = "",
+        task_id: str = "",
+        max_retries: int = 3,
+    ) -> Dict:
+        """Run command, auto-repair on failure, retry."""
+
+        attempt = 0
+        last_result = None
+
+        while attempt < max_retries:
+            attempt += 1
+
+            if self.ws and task_id and attempt > 1:
+                await self.ws.emit(task_id, "retry_attempt", {
+                    "attempt": attempt,
+                    "max_retries": max_retries,
+                    "command": command[:80],
+                }, session_id=session_id)
+
+            result = await self.terminal.execute(command, session_id=session_id, task_id=task_id)
+            last_result = result
+
+            if result["success"]:
+                if attempt > 1:
+                    if self.ws and task_id:
+                        await self.ws.emit(task_id, "self_heal_success", {
+                            "attempts": attempt,
+                            "command": command[:80],
+                        }, session_id=session_id)
+                return {**result, "attempts": attempt, "self_healed": attempt > 1}
+
+            # Failed — analyze error and attempt repair
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "self_heal_attempt", {
+                    "attempt": attempt,
+                    "error_snippet": result["output"][-500:],
+                    "command": command[:80],
+                }, session_id=session_id)
+
+            if not self.ai_router:
+                break
+
+            # Ask AI to analyze error and suggest fix
+            patch = await self._analyze_and_repair(
+                command=command,
+                error_output=result["output"],
+                related_files=related_files,
+                session_id=session_id,
+                task_id=task_id,
+            )
+
+            if patch and patch.get("fixed"):
+                # Apply patches to files
+                for file_patch in patch.get("file_patches", []):
+                    fpath = file_patch.get("file", "")
+                    old = file_patch.get("old", "")
+                    new = file_patch.get("new", "")
+                    if fpath and old and new:
+                        await self.filesystem.patch_file(fpath, old, new, session_id=session_id, task_id=task_id)
+
+                # Update command if needed
+                if patch.get("new_command"):
+                    command = patch["new_command"]
+
+                # Install missing packages if needed
+                if patch.get("install_command"):
+                    await self.terminal.execute(patch["install_command"], session_id=session_id, task_id=task_id)
+
+            await asyncio.sleep(1)
+
+        # All retries exhausted
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "self_heal_failed", {
+                "attempts": attempt,
+                "final_error": (last_result or {}).get("output", "")[-300:],
+            }, session_id=session_id)
+
+        return {**(last_result or {}), "attempts": attempt, "self_healed": False}
+
+    async def _analyze_and_repair(
+        self,
+        command: str,
+        error_output: str,
+        related_files: List[str],
+        session_id: str,
+        task_id: str,
+    ) -> Dict:
+        """Use AI to analyze error and produce repair instructions."""
+
+        # Read related file contents for context
+        file_context = ""
+        for fp in related_files[:3]:
+            try:
+                full_path = os.path.join(WORKSPACE, fp)
+                if os.path.exists(full_path):
+                    with open(full_path, "r", errors="replace") as f:
+                        content = f.read()[:1000]
+                    file_context += f"\n\nFile: {fp}\n```\n{content}\n```"
+            except Exception:
+                pass
+
+        messages = [
+            {
+                "role": "system",
+                "content": (
+                    "You are an expert debugger. Analyze the error and provide a precise repair.\n"
+                    "Respond ONLY with valid JSON.\n"
+                    "Format:\n"
+                    '{"fixed": true/false, '
+                    '"analysis": "brief error explanation", '
+                    '"fix_description": "what to fix", '
+                    '"install_command": "pip install X or npm install X if missing package, else null", '
+                    '"new_command": "corrected command if needed, else null", '
+                    '"file_patches": [{"file": "filename", "old": "exact old text", "new": "exact new text"}]}'
+                ),
+            },
+            {
+                "role": "user",
+                "content": (
+                    f"Command that failed:\n```\n{command}\n```\n\n"
+                    f"Error output:\n```\n{error_output[-2000:]}\n```"
+                    f"{file_context}"
+                ),
+            },
+        ]
+
+        try:
+            raw = await self.ai_router.complete(messages, temperature=0.1, max_tokens=1000)
+            start = raw.find("{")
+            end = raw.rfind("}") + 1
+            if start >= 0 and end > start:
+                return json.loads(raw[start:end])
+        except Exception as e:
+            log.warning("Self-repair analysis failed", error=str(e))
+
+        return {"fixed": False}
+
+
+# ═══════════════════════════════════════════════════════════════════
+# DEPLOYMENT ENGINE
+# ═══════════════════════════════════════════════════════════════════
+
+class DeploymentEngine:
+    """Deployment automation for Vercel + HuggingFace."""
+
+    def __init__(self, ws_manager=None):
+        self.ws = ws_manager
+        self.vercel_token = VERCEL_TOKEN
+        self.hf_token = HF_TOKEN
+
+    async def deploy_vercel(
+        self,
+        project_dir: str,
+        project_name: str,
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Deploy a project to Vercel."""
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "deploy_start", {
+                "platform": "vercel",
+                "project": project_name,
+            }, session_id=session_id)
+
+        # Use vercel CLI if available
+        env = {**os.environ, "VERCEL_TOKEN": self.vercel_token}
+        try:
+            proc = await asyncio.create_subprocess_shell(
+                f"cd {project_dir} && npx vercel --token={self.vercel_token} --yes --prod 2>&1",
+                stdout=asyncio.subprocess.PIPE,
+                stderr=asyncio.subprocess.STDOUT,
+                env=env,
+            )
+            stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=300)
+            output = stdout.decode("utf-8", errors="replace")
+
+            # Extract URL from output
+            url_match = re.search(r"https://[a-zA-Z0-9\-]+\.vercel\.app", output)
+            url = url_match.group(0) if url_match else ""
+
+            success = proc.returncode == 0 and bool(url)
+
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "deploy_complete", {
+                    "platform": "vercel",
+                    "success": success,
+                    "url": url,
+                    "project": project_name,
+                }, session_id=session_id)
+
+            return {"success": success, "url": url, "output": output[-1000:], "platform": "vercel"}
+
+        except Exception as e:
+            return {"success": False, "error": str(e), "platform": "vercel"}
+
+    async def deploy_hf_space(
+        self,
+        repo_path: str,
+        space_name: str,
+        space_type: str = "gradio",
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Push to HuggingFace Space."""
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "deploy_start", {
+                "platform": "huggingface",
+                "space": space_name,
+            }, session_id=session_id)
+
+        hf_url = f"https://huggingface.co/spaces/{space_name}"
+        git_url = f"https://huggingface.co/spaces/{space_name}.git"
+
+        # Inject HF token
+        auth_url = git_url.replace("https://", f"https://user:{self.hf_token}@")
+
+        try:
+            cmds = [
+                f"cd {repo_path} && git remote remove hf_space 2>/dev/null; git remote add hf_space {auth_url}",
+                f"cd {repo_path} && git push hf_space main --force 2>&1",
+            ]
+            results = []
+            for cmd in cmds:
+                proc = await asyncio.create_subprocess_shell(cmd, stdout=asyncio.subprocess.PIPE, stderr=asyncio.subprocess.STDOUT)
+                stdout, _ = await asyncio.wait_for(proc.communicate(), timeout=120)
+                results.append({"cmd": cmd[:40], "success": proc.returncode == 0, "out": stdout.decode("utf-8", errors="replace")[:300]})
+
+            success = results[-1]["success"]
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "deploy_complete", {
+                    "platform": "huggingface",
+                    "success": success,
+                    "url": hf_url,
+                    "space": space_name,
+                }, session_id=session_id)
+
+            return {"success": success, "url": hf_url, "platform": "huggingface", "steps": results}
+
+        except Exception as e:
+            return {"success": False, "error": str(e), "platform": "huggingface"}
+
+
+# ═══════════════════════════════════════════════════════════════════
+# UNIFIED REAL TOOL ROUTER
+# ═══════════════════════════════════════════════════════════════════
+
+class RealToolRouter:
+    """
+    Routes tool calls to real implementations.
+    This is the core of the autonomous execution system.
+    """
+
+    def __init__(self, ws_manager=None, ai_router=None):
+        self.ws = ws_manager
+        self.ai_router = ai_router
+        self.terminal = TerminalEngine(ws_manager=ws_manager)
+        self.filesystem = FilesystemEngine(ws_manager=ws_manager)
+        self.github = GitHubEngine(ws_manager=ws_manager)
+        self.repair = SelfRepairEngine(
+            terminal=self.terminal,
+            filesystem=self.filesystem,
+            ai_router=ai_router,
+            ws_manager=ws_manager,
+        )
+        self.deployment = DeploymentEngine(ws_manager=ws_manager)
+
+    async def route(
+        self,
+        tool: str,
+        params: Dict,
+        session_id: str = "",
+        task_id: str = "",
+    ) -> Dict:
+        """Route a tool call to the correct engine."""
+
+        # Emit tool call event
+        if self.ws and task_id:
+            await self.ws.emit(task_id, "tool_called", {
+                "tool": tool,
+                "params_preview": str(params)[:100],
+            }, session_id=session_id)
+
+        handlers = {
+            # Terminal
+            "terminal.run": self._terminal_run,
+            "terminal.sequence": self._terminal_sequence,
+            "terminal.run_with_repair": self._terminal_repair,
+
+            # Filesystem
+            "fs.read": self._fs_read,
+            "fs.write": self._fs_write,
+            "fs.patch": self._fs_patch,
+            "fs.delete": self._fs_delete,
+            "fs.move": self._fs_move,
+            "fs.search": self._fs_search,
+            "fs.tree": self._fs_tree,
+            "fs.list": self._fs_list,
+
+            # GitHub
+            "github.clone": self._github_clone,
+            "github.create_repo": self._github_create_repo,
+            "github.commit_push": self._github_commit_push,
+            "github.create_branch": self._github_create_branch,
+            "github.create_pr": self._github_create_pr,
+            "github.read_issues": self._github_issues,
+
+            # Deployment
+            "deploy.vercel": self._deploy_vercel,
+            "deploy.hf": self._deploy_hf,
+
+            # Meta
+            "workspace.info": self._workspace_info,
+        }
+
+        handler = handlers.get(tool)
+        if not handler:
+            return {"success": False, "error": f"Unknown tool: {tool}", "available": list(handlers.keys())}
+
+        try:
+            result = await handler(params, session_id=session_id, task_id=task_id)
+
+            # Emit result event
+            if self.ws and task_id:
+                await self.ws.emit(task_id, "tool_result", {
+                    "tool": tool,
+                    "success": result.get("success", True),
+                    "summary": str(result)[:150],
+                }, session_id=session_id)
+
+            return result
+        except Exception as e:
+            log.error("Tool execution failed", tool=tool, error=str(e))
+            return {"success": False, "error": str(e), "tool": tool}
+
+    # ─── Terminal Handlers ────────────────────────────────────────────────────
+    async def _terminal_run(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.terminal.execute(
+            params.get("command", ""),
+            session_id=session_id,
+            task_id=task_id,
+            cwd=params.get("cwd"),
+            timeout=params.get("timeout", 60),
+        )
+
+    async def _terminal_sequence(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        results = await self.terminal.run_sequence(
+            params.get("commands", []),
+            session_id=session_id,
+            task_id=task_id,
+            stop_on_error=params.get("stop_on_error", True),
+        )
+        return {"success": all(r["success"] for r in results), "steps": results}
+
+    async def _terminal_repair(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.repair.run_with_repair(
+            params.get("command", ""),
+            related_files=params.get("related_files", []),
+            session_id=session_id,
+            task_id=task_id,
+            max_retries=params.get("max_retries", 3),
+        )
+
+    # ─── Filesystem Handlers ──────────────────────────────────────────────────
+    async def _fs_read(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.read_file(params.get("path", ""), session_id=session_id, task_id=task_id)
+
+    async def _fs_write(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.write_file(params.get("path", ""), params.get("content", ""), session_id=session_id, task_id=task_id)
+
+    async def _fs_patch(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.patch_file(params.get("path", ""), params.get("old", ""), params.get("new", ""), session_id=session_id, task_id=task_id)
+
+    async def _fs_delete(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.delete_file(params.get("path", ""), session_id=session_id, task_id=task_id)
+
+    async def _fs_move(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.move_file(params.get("src", ""), params.get("dst", ""), session_id=session_id, task_id=task_id)
+
+    async def _fs_search(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.search_files(params.get("query", ""), params.get("path", ""), params.get("pattern", "*"))
+
+    async def _fs_tree(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.tree(params.get("path", ""), params.get("max_depth", 4))
+
+    async def _fs_list(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.filesystem.list_dir(params.get("path", ""))
+
+    # ─── GitHub Handlers ─────────────────────────────────────────────────────���
+    async def _github_clone(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.github.clone_repo(params.get("url", ""), params.get("target", ""), session_id=session_id, task_id=task_id)
+
+    async def _github_create_repo(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.github.create_repo(params.get("name", ""), params.get("description", ""), params.get("private", False), session_id=session_id, task_id=task_id)
+
+    async def _github_commit_push(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.github.commit_and_push(params.get("repo_path", WORKSPACE), params.get("message", "God Agent commit"), params.get("branch", "main"), session_id=session_id, task_id=task_id)
+
+    async def _github_create_branch(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.github.create_branch(params.get("repo_path", WORKSPACE), params.get("branch", ""), session_id=session_id, task_id=task_id)
+
+    async def _github_create_pr(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.github.create_pr(params.get("owner", ""), params.get("repo", ""), params.get("title", ""), params.get("body", ""), params.get("head", ""), session_id=session_id, task_id=task_id)
+
+    async def _github_issues(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        issues = await self.github.read_issues(params.get("owner", ""), params.get("repo", ""))
+        return {"success": True, "issues": issues}
+
+    # ─── Deployment Handlers ──────────────────────────────────────────────────
+    async def _deploy_vercel(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.deployment.deploy_vercel(params.get("dir", WORKSPACE), params.get("name", "god-agent-app"), session_id=session_id, task_id=task_id)
+
+    async def _deploy_hf(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        return await self.deployment.deploy_hf_space(params.get("repo_path", WORKSPACE), params.get("space_name", ""), session_id=session_id, task_id=task_id)
+
+    # ─── Meta ─────────────────────────────────────────────────────────────────
+    async def _workspace_info(self, params: Dict, session_id: str, task_id: str) -> Dict:
+        tree = await self.filesystem.tree()
+        return {
+            "success": True,
+            "workspace": WORKSPACE,
+            "files": tree.get("files", []),
+            "file_count": tree.get("count", 0),
+        }
+
+
+# ─── Singleton instance ────────────────────────────────────────────────────────
+_tool_router: Optional[RealToolRouter] = None
+
+def get_tool_router(ws_manager=None, ai_router=None) -> RealToolRouter:
+    global _tool_router
+    if _tool_router is None:
+        _tool_router = RealToolRouter(ws_manager=ws_manager, ai_router=ai_router)
+    return _tool_router