a4e 0.1.5__py3-none-any.whl

a4e/tools/views/list_views.py

@@ -0,0 +1,27 @@
+"""
+List views tool.
+"""
+
+from typing import Optional
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def list_views(agent_name: Optional[str] = None) -> dict:
+    """
+    List all views available in the current agent project
+    """
+    project_dir = get_project_dir(agent_name)
+    views_dir = project_dir / "views"
+
+    if not views_dir.exists():
+        return {"views": [], "count": 0}
+
+    views = []
+    for view_dir in views_dir.iterdir():
+        if view_dir.is_dir() and (view_dir / "view.tsx").exists():
+            views.append(view_dir.name)
+
+    return {"views": sorted(views), "count": len(views)}
+

a4e/tools/views/remove_view.py

@@ -0,0 +1,73 @@
+"""
+Remove view tool.
+"""
+
+from pathlib import Path
+from typing import Optional
+import json
+import shutil
+
+from ...core import mcp, get_project_dir
+
+
+@mcp.tool()
+def remove_view(
+    view_id: str,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Remove a view from the agent
+
+    Args:
+        view_id: ID of the view to remove (the folder name)
+        agent_name: Optional agent ID if not in agent directory
+
+    Returns:
+        Result with success status and removed folder path
+    """
+    project_dir = get_project_dir(agent_name)
+    views_dir = project_dir / "views"
+
+    if not views_dir.exists():
+        return {
+            "success": False,
+            "error": f"views/ directory not found at {views_dir}. Are you in an agent project?",
+        }
+
+    view_folder = views_dir / view_id
+
+    if not view_folder.exists():
+        return {
+            "success": False,
+            "error": f"View '{view_id}' not found at {view_folder}",
+        }
+
+    # Prevent removing the mandatory welcome view
+    if view_id == "welcome":
+        return {
+            "success": False,
+            "error": "Cannot remove the 'welcome' view - it is required for all agents",
+        }
+
+    try:
+        # Remove the view folder and all its contents
+        shutil.rmtree(view_folder)
+
+        # Update schemas.json if it exists
+        schemas_file = views_dir / "schemas.json"
+        if schemas_file.exists():
+            try:
+                schemas = json.loads(schemas_file.read_text())
+                if view_id in schemas:
+                    del schemas[view_id]
+                    schemas_file.write_text(json.dumps(schemas, indent=2))
+            except (json.JSONDecodeError, KeyError):
+                pass  # Ignore schema update errors
+
+        return {
+            "success": True,
+            "message": f"Removed view '{view_id}'",
+            "removed_folder": str(view_folder),
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

a4e/tools/views/update_view.py

@@ -0,0 +1,124 @@
+"""
+Update view - modify existing view's description or props.
+"""
+
+import json
+from typing import Optional
+
+from ...core import mcp, jinja_env, get_project_dir
+
+
+@mcp.tool()
+def update_view(
+    view_id: str,
+    description: Optional[str] = None,
+    props: Optional[dict] = None,
+    agent_name: Optional[str] = None,
+) -> dict:
+    """
+    Update an existing view's description or props.
+
+    Args:
+        view_id: ID of the view to update
+        description: New description (optional)
+        props: New props dict (optional, replaces all props)
+        agent_name: Optional agent ID if not in agent directory
+    """
+    project_dir = get_project_dir(agent_name)
+    views_dir = project_dir / "views"
+
+    if not views_dir.exists():
+        return {
+            "success": False,
+            "error": f"views/ directory not found at {views_dir}",
+            "fix": "Make sure you're in an agent project directory or specify agent_name",
+        }
+
+    view_dir = views_dir / view_id
+    if not view_dir.exists():
+        # List available views for helpful error
+        available = [d.name for d in views_dir.iterdir() if d.is_dir() and not d.name.startswith("_")]
+        return {
+            "success": False,
+            "error": f"View '{view_id}' not found",
+            "fix": f"Available views: {', '.join(available) if available else 'none'}",
+        }
+
+    if description is None and props is None:
+        return {
+            "success": False,
+            "error": "Nothing to update",
+            "fix": "Provide at least one of: description, props",
+        }
+
+    try:
+        # Read current schema to get existing values
+        schema_file = view_dir / "view.schema.json"
+        if schema_file.exists():
+            current_schema = json.loads(schema_file.read_text())
+            if description is None:
+                description = current_schema.get("description", f"View: {view_id}")
+            if props is None:
+                # Extract props from schema
+                props = {}
+                for prop_name, prop_info in current_schema.get("props", {}).get("properties", {}).items():
+                    props[prop_name] = prop_info.get("type", "string")
+        else:
+            if description is None:
+                description = f"View: {view_id}"
+            if props is None:
+                return {
+                    "success": False,
+                    "error": "Props must be specified when no schema exists",
+                    "fix": "Provide the props dict with all props for the view",
+                }
+
+        # Convert snake_case to PascalCase for component name
+        view_name = "".join(word.title() for word in view_id.split("_"))
+
+        # Regenerate view.tsx
+        template = jinja_env.get_template("view.tsx.j2")
+        code = template.render(view_name=view_name, description=description, props=props)
+        (view_dir / "view.tsx").write_text(code)
+
+        # Regenerate view.schema.json
+        schema_properties = {}
+        required_props = []
+        for prop_name, prop_type in props.items():
+            if isinstance(prop_type, dict):
+                schema_properties[prop_name] = {
+                    "type": prop_type.get("type", "string"),
+                    "description": prop_type.get("description", f"The {prop_name} prop"),
+                }
+                if prop_type.get("required", True):
+                    required_props.append(prop_name)
+            else:
+                schema_properties[prop_name] = {
+                    "type": prop_type,
+                    "description": f"The {prop_name} prop",
+                }
+                required_props.append(prop_name)
+
+        view_schema = {
+            "name": view_id,
+            "description": description,
+            "props": {
+                "type": "object",
+                "properties": schema_properties,
+                "required": required_props,
+            },
+        }
+        (view_dir / "view.schema.json").write_text(json.dumps(view_schema, indent=2))
+
+        # Regenerate schemas
+        from ..schemas import generate_schemas
+        generate_schemas(force=True, agent_name=agent_name)
+
+        return {
+            "success": True,
+            "message": f"Updated view '{view_id}'",
+            "path": str(view_dir),
+            "files": ["view.tsx", "view.schema.json"],
+        }
+    except Exception as e:
+        return {"success": False, "error": str(e)}

a4e/utils/dev_manager.py

@@ -0,0 +1,253 @@
+import subprocess
+import shutil
+import time
+import sys
+import re
+from pathlib import Path
+from typing import Optional, Dict, Any
+from urllib.parse import urlencode
+
+HUB_URL = "https://dev-a4e.global.simetrik.com"
+
+
+class DevManager:
+    """Manages the development server and ngrok tunnel lifecycle."""
+
+    @staticmethod
+    def stop_dev_server(port: int = 5000) -> Dict[str, Any]:
+        """
+        Stop development server and cleanup tunnels.
+
+        Args:
+            port: Port to cleanup.
+
+        Returns:
+            Dictionary with cleanup status.
+        """
+        try:
+            DevManager._cleanup_port(port)
+            return {
+                "success": True,
+                "message": f"Dev server stopped and port {port} cleaned up.",
+            }
+        except Exception as e:
+            return {"success": False, "error": f"Failed to stop dev server: {str(e)}"}
+
+    @staticmethod
+    def _cleanup_port(port: int):
+        """Kill any process using the specified port and any ngrok process."""
+        try:
+            # 1. Kill process on port (lsof on Mac/Linux)
+            # Find PID using port
+            cmd = f"lsof -t -i:{port}"
+            try:
+                pid = subprocess.check_output(cmd, shell=True).decode().strip()
+                if pid:
+                    print(f"Killing process {pid} on port {port}")
+                    subprocess.run(f"kill -9 {pid}", shell=True)
+            except subprocess.CalledProcessError:
+                pass  # No process found
+
+            # 2. Kill orphan ngrok processes
+            # This is a bit aggressive but ensures clean state as requested
+            try:
+                subprocess.run("pkill -f ngrok", shell=True)
+            except Exception:
+                pass
+
+        except Exception as e:
+            print(f"Warning during cleanup: {e}")
+
+    @staticmethod
+    def start_dev_server(
+        project_dir: Path, port: int = 5000, auth_token: Optional[str] = None
+    ) -> Dict[str, Any]:
+        """
+        Start the agent runner and ngrok tunnel.
+
+        Args:
+            project_dir: Path to the agent project directory.
+            port: Port to run the server on.
+            auth_token: Optional ngrok auth token.
+
+        Returns:
+            Dictionary with success status and connection details.
+        """
+        if not project_dir.exists():
+            return {
+                "success": False,
+                "error": f"Project directory {project_dir} does not exist",
+            }
+
+        # Perform cleanup before starting
+        DevManager._cleanup_port(port)
+
+        # 1. Start the Agent Server (Dev Runner)
+        # We assume dev_runner.py is in the parent directory of this file's parent (a4e/dev_runner.py)
+        # utils/dev_manager.py -> a4e/utils/dev_manager.py
+        # We need a4e/dev_runner.py
+
+        # Get the package root (a4e)
+        package_root = Path(__file__).parent.parent
+        runner_script = package_root / "dev_runner.py"
+
+        if not runner_script.exists():
+            return {
+                "success": False,
+                "error": f"Runner script not found at {runner_script}",
+            }
+
+        print(f"Starting agent server on port {port}...")
+        server_process = subprocess.Popen(
+            [
+                sys.executable,
+                str(runner_script),
+                "--agent-path",
+                str(project_dir),
+                "--port",
+                str(port),
+            ],
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+        )
+
+        # Give it a moment to start
+        time.sleep(2)
+        if server_process.poll() is not None:
+            stdout, stderr = server_process.communicate()
+            error_details = ""
+            if stdout:
+                error_details += f"STDOUT:\n{stdout}\n"
+            if stderr:
+                error_details += f"STDERR:\n{stderr}\n"
+
+            return {
+                "success": False,
+                "error": "Agent server failed to start (likely port already in use)",
+                "details": error_details or "No output captured",
+            }
+
+        agent_id = project_dir.name
+
+        # 2. Start ngrok Tunnel
+        return DevManager._start_ngrok(agent_id, port, auth_token, server_process)
+
+    @staticmethod
+    def _start_ngrok(
+        agent_id: str,
+        port: int,
+        auth_token: Optional[str],
+        server_process: subprocess.Popen,
+    ) -> Dict[str, Any]:
+        """Internal helper to start ngrok via library or CLI."""
+        public_url = None
+        method = "unknown"
+
+        # Try pyngrok first
+        try:
+            from pyngrok import ngrok, conf  # type: ignore
+
+            if auth_token:
+                conf.get_default().auth_token = auth_token
+
+            # Smartly manage tunnels instead of killing all
+            try:
+                tunnels = ngrok.get_tunnels()
+                for t in tunnels:
+                    # Check if tunnel matches our port
+                    # t.config is a dict with 'addr', e.g., 'http://localhost:5000' or just '5000'
+                    addr = str(t.config.get("addr", ""))
+                    # Match exact port at end of addr or as standalone value
+                    if addr.endswith(f":{port}") or addr == str(port):
+                        print(
+                            f"Disconnecting existing tunnel for port {port}: {t.public_url}"
+                        )
+                        ngrok.disconnect(t.public_url)
+            except Exception as e:
+                print(f"Warning: Failed to enumerate/disconnect tunnels: {e}")
+                # We don't kill() here to be safe, just proceed and hope for the best
+
+            tunnel = ngrok.connect(port)
+            public_url = tunnel.public_url
+            method = "pyngrok"
+        except ImportError:
+            # Fallback to ngrok CLI
+            ngrok_path = shutil.which("ngrok")
+            if not ngrok_path:
+                server_process.kill()
+                return {
+                    "success": False,
+                    "error": "Neither 'pyngrok' library nor 'ngrok' CLI found.",
+                    "fix": "Run 'uv add pyngrok' OR install ngrok CLI.",
+                }
+
+            # Start ngrok CLI process
+            try:
+                if auth_token:
+                    subprocess.run(
+                        [ngrok_path, "config", "add-authtoken", auth_token], check=True
+                    )
+
+                ngrok_process = subprocess.Popen(
+                    [ngrok_path, "http", str(port), "--log=stdout"],
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE,
+                    text=True,
+                )
+
+                # Read stdout to find the URL
+                start_time = time.time()
+                while time.time() - start_time < 10:
+                    line = ngrok_process.stdout.readline()  # type: ignore
+                    if not line:
+                        break
+
+                    # Look for "url=https://..." with support for all ngrok domains
+                    match = re.search(
+                        r"url=(https://[a-zA-Z0-9-]+\.(?:ngrok\.app|ngrok\.dev|ngrok\.pizza|ngrok-free\.app|ngrok-free\.dev|ngrok-free\.pizza|ngrok\.io|ngrok-free\.io))",
+                        line,
+                    )
+                    if match:
+                        public_url = match.group(1)
+                        method = "ngrok_cli"
+                        break
+
+                if not public_url:
+                    server_process.kill()
+                    ngrok_process.kill()
+                    return {
+                        "success": False,
+                        "error": "Failed to get public URL from ngrok CLI",
+                        "details": "Timeout waiting for URL",
+                    }
+
+            except Exception as e:
+                server_process.kill()
+                return {
+                    "success": False,
+                    "error": f"Failed to start ngrok CLI: {str(e)}",
+                }
+
+        except Exception as e:
+            server_process.kill()
+            return {"success": False, "error": f"Failed to start tunnel: {str(e)}"}
+
+        if public_url:
+
+            return {
+                "success": True,
+                "message": f"Dev mode started successfully via {method}",
+                "public_url": public_url,
+                "hub_url": f"{HUB_URL}/builder/playground?{urlencode({'url': public_url, 'agent': agent_id} )}",
+                "instructions": [
+                    "1. Copy the Hub URL above",
+                    "2. Open it in your browser",
+                    "3. Your local agent is now connected to the Hub!",
+                    "4. Press Ctrl+C to stop the server",
+                ],
+                "pid": server_process.pid,
+            }
+
+        server_process.kill()
+        return {"success": False, "error": "Unknown error starting tunnel"}