agent-portal-2 0.1.0

package/python/agent_portal/cli.py

@@ -0,0 +1,164 @@
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import asdict
+from pathlib import Path
+import sys
+from urllib.error import HTTPError, URLError
+from urllib.request import Request, urlopen
+
+from .config import load_config, save_default_config
+from .doctor import run_doctor
+from .plugin_system import discover_plugins, validate_plugin_manifest
+from .runtime import PortalRuntime
+from .server import serve
+
+
+def main() -> None:
+    parser = build_parser()
+    args = parser.parse_args()
+    workspace = Path.cwd()
+    save_default_config(workspace)
+    config = load_config(workspace)
+    host = args.host or config.runtime_host
+    port = args.port or config.runtime_port
+    runtime_url = f"http://{host}:{port}"
+
+    config.runtime_host = host
+    config.runtime_port = port
+
+    try:
+        if args.command == "start":
+            serve(PortalRuntime(workspace, config))
+            return
+        if args.command == "stop":
+            print_json_or_text(post_json(f"{runtime_url}/control/stop"), args.json)
+            return
+        if args.command == "status":
+            print_json_or_text(get_json(f"{runtime_url}/status"), args.json)
+            return
+        if args.command == "doctor":
+            report = run_doctor(workspace)
+            payload = {"checks": [asdict(check) for check in report.checks]}
+            print_json_or_text(payload, args.json)
+            return
+        if args.command == "open":
+            payload = {"url": args.url}
+            print_json_or_text(post_json(f"{runtime_url}/browser/open", payload), args.json)
+            return
+        if args.command == "screenshot":
+            payload = {"label": args.label}
+            print_json_or_text(post_json(f"{runtime_url}/browser/screenshot", payload), args.json)
+            return
+        if args.command == "report":
+            print_json_or_text(post_json(f"{runtime_url}/report/generate"), args.json)
+            return
+        if args.command == "plugins":
+            if args.plugins_command == "list":
+                payload = [str(path) for path in discover_plugins(workspace)]
+                print_json_or_text(payload, args.json)
+                return
+            if args.plugins_command == "validate":
+                results = {
+                    str(path): validate_plugin_manifest(path)
+                    for path in discover_plugins(workspace)
+                }
+                print_json_or_text(results, args.json)
+                return
+        if args.command == "mcp":
+            mcp_cli = load_mcp_cli_module()
+            argv = [args.mcp_command]
+            if args.host or args.port:
+                argv.extend(["--runtime-url", runtime_url])
+            if args.json:
+                argv.append("--json")
+            old_argv = sys.argv[:]
+            try:
+                sys.argv = ["agent-portal-mcp", *argv]
+                mcp_cli.main()
+            finally:
+                sys.argv = old_argv
+            return
+    except (HTTPError, URLError) as exc:
+        print_json_or_text(
+            {
+                "error": "Runtime request failed",
+                "details": str(exc),
+                "suggestedFix": f"Start the runtime with `agent-portal --host {host} --port {port} start`.",
+            },
+            True if args.json else False,
+        )
+        raise SystemExit(1) from exc
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="agent-portal")
+    parser.add_argument("--json", action="store_true")
+    parser.add_argument("--verbose", action="store_true")
+    parser.add_argument("--debug", action="store_true")
+    parser.add_argument("--host")
+    parser.add_argument("--port", type=int)
+    parser.add_argument("--profile")
+
+    subparsers = parser.add_subparsers(dest="command", required=True)
+    subparsers.add_parser("start")
+    subparsers.add_parser("stop")
+    subparsers.add_parser("status")
+    subparsers.add_parser("doctor")
+
+    open_parser = subparsers.add_parser("open")
+    open_parser.add_argument("url")
+
+    screenshot_parser = subparsers.add_parser("screenshot")
+    screenshot_parser.add_argument("--label", default="manual")
+
+    subparsers.add_parser("report")
+
+    plugins_parser = subparsers.add_parser("plugins")
+    plugins_subparsers = plugins_parser.add_subparsers(dest="plugins_command", required=True)
+    plugins_subparsers.add_parser("list")
+    plugins_subparsers.add_parser("validate")
+
+    mcp_parser = subparsers.add_parser("mcp")
+    mcp_subparsers = mcp_parser.add_subparsers(dest="mcp_command", required=True)
+    mcp_subparsers.add_parser("start")
+    mcp_subparsers.add_parser("doctor")
+    return parser
+
+
+def get_json(url: str) -> object:
+    with urlopen(url) as response:
+        return json.loads(response.read().decode("utf8"))
+
+
+def post_json(url: str, payload: dict[str, object] | None = None) -> object:
+    data = json.dumps(payload or {}).encode("utf8")
+    request = Request(url, data=data, headers={"Content-Type": "application/json"})
+    with urlopen(request) as response:
+        return json.loads(response.read().decode("utf8"))
+
+
+def print_json_or_text(payload: object, json_output: bool) -> None:
+    if json_output:
+        print(json.dumps(payload, indent=2))
+        return
+    if isinstance(payload, dict):
+        for key, value in payload.items():
+            print(f"{key}: {value}")
+        return
+    if isinstance(payload, list):
+        for entry in payload:
+            print(f"- {entry}")
+        return
+    print(payload)
+
+
+def load_mcp_cli_module():
+    repo_root = Path(__file__).resolve().parents[2]
+    mcp_src = repo_root / "packages" / "agent-portal-mcp"
+    if str(mcp_src) not in sys.path:
+        sys.path.insert(0, str(mcp_src))
+    from agent_portal_mcp import cli as mcp_cli  # type: ignore
+
+    return mcp_cli

package/python/agent_portal/config.py

@@ -0,0 +1,31 @@
+from __future__ import annotations
+
+import json
+from dataclasses import asdict
+from pathlib import Path
+
+from .models import RuntimeConfigModel
+
+
+DEFAULT_CONFIG_PATH = "agent-portal.config.json"
+
+
+def load_config(base_path: Path | None = None) -> RuntimeConfigModel:
+    root = base_path or Path.cwd()
+    config_path = root / DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        return RuntimeConfigModel()
+
+    raw = json.loads(config_path.read_text(encoding="utf8"))
+    return RuntimeConfigModel(**raw)
+
+
+def save_default_config(base_path: Path | None = None) -> Path:
+    root = base_path or Path.cwd()
+    config_path = root / DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        config_path.write_text(
+            json.dumps(asdict(RuntimeConfigModel()), indent=2),
+            encoding="utf8",
+        )
+    return config_path

package/python/agent_portal/doctor.py

@@ -0,0 +1,165 @@
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import socket
+import sys
+from pathlib import Path
+
+from .config import DEFAULT_CONFIG_PATH, load_config
+from .models import DoctorReport, HealthCheckResult
+from .plugin_system import discover_plugins, validate_plugin_manifest
+
+
+def run_doctor(base_path: Path | None = None) -> DoctorReport:
+    root = base_path or Path.cwd()
+    config = load_config(root)
+    report = DoctorReport()
+
+    report.checks.append(check_python_version())
+    report.checks.append(check_dependency("playwright", "Install with `pip install -e ./python`."))
+    report.checks.append(check_config_file(root))
+    report.checks.append(check_runtime_port(config.runtime_host, config.runtime_port))
+    report.checks.append(check_directory_writable(root / config.screenshot_directory, "Screenshot directory"))
+    report.checks.append(check_directory_writable(root / config.report_directory, "Report directory"))
+    report.checks.extend(check_plugin_manifests(root))
+    report.checks.append(check_vscode_extension(root))
+    report.checks.append(check_os_support())
+    report.checks.append(check_chromium_presence())
+    return report
+
+
+def check_python_version() -> HealthCheckResult:
+    if sys.version_info >= (3, 10):
+        return HealthCheckResult("python-version", "passed", sys.version.split()[0])
+    return HealthCheckResult(
+        "python-version",
+        "failed",
+        sys.version.split()[0],
+        "Install Python 3.10 or newer.",
+    )
+
+
+def check_dependency(module_name: str, suggested_fix: str) -> HealthCheckResult:
+    found = importlib.util.find_spec(module_name) is not None
+    if found:
+        return HealthCheckResult(module_name, "passed", "Installed")
+    return HealthCheckResult(module_name, "failed", "Missing", suggested_fix)
+
+
+def check_config_file(root: Path) -> HealthCheckResult:
+    config_path = root / DEFAULT_CONFIG_PATH
+    if not config_path.exists():
+        return HealthCheckResult(
+            "config-file",
+            "warning",
+            f"{config_path.name} not found",
+            "Start the runtime once or create the default config with `agent-portal start`.",
+        )
+    try:
+        json.loads(config_path.read_text(encoding="utf8"))
+        return HealthCheckResult("config-file", "passed", str(config_path))
+    except json.JSONDecodeError as exc:
+        return HealthCheckResult(
+            "config-file",
+            "failed",
+            str(exc),
+            "Fix the JSON syntax in agent-portal.config.json.",
+        )
+
+
+def check_runtime_port(host: str, port: int) -> HealthCheckResult:
+    sock = socket.socket()
+    try:
+        sock.bind((host, port))
+        return HealthCheckResult("runtime-port", "passed", f"{host}:{port} is available")
+    except OSError:
+        return HealthCheckResult(
+            "runtime-port",
+            "warning",
+            f"{host}:{port} is already in use",
+            "Stop the other runtime or choose a different port.",
+        )
+    finally:
+        sock.close()
+
+
+def check_directory_writable(directory: Path, label: str) -> HealthCheckResult:
+    try:
+        directory.mkdir(parents=True, exist_ok=True)
+        test_file = directory / ".write-test"
+        test_file.write_text("ok", encoding="utf8")
+        test_file.unlink()
+        return HealthCheckResult(label, "passed", str(directory))
+    except OSError as exc:
+        return HealthCheckResult(
+            label,
+            "failed",
+            str(exc),
+            f"Fix filesystem permissions for {directory}.",
+        )
+
+
+def check_plugin_manifests(root: Path) -> list[HealthCheckResult]:
+    results: list[HealthCheckResult] = []
+    for plugin_manifest in discover_plugins(root):
+        errors = validate_plugin_manifest(plugin_manifest)
+        if errors:
+            results.append(
+                HealthCheckResult(
+                    f"plugin:{plugin_manifest.parent.name}",
+                    "failed",
+                    "; ".join(errors),
+                    "Fix the manifest fields and retry.",
+                )
+            )
+        else:
+            results.append(
+                HealthCheckResult(
+                    f"plugin:{plugin_manifest.parent.name}",
+                    "passed",
+                    "Valid"
+                )
+            )
+    return results
+
+
+def check_vscode_extension(root: Path) -> HealthCheckResult:
+    extension_dir = root / "apps" / "vscode-extension"
+    package_json = extension_dir / "package.json"
+    if package_json.exists():
+        return HealthCheckResult("vscode-extension", "passed", str(package_json))
+    return HealthCheckResult(
+        "vscode-extension",
+        "warning",
+        str(package_json),
+        "Restore the VS Code extension package if editor integration is required.",
+    )
+
+
+def check_os_support() -> HealthCheckResult:
+    if os.name == "nt":
+        return HealthCheckResult("os-support", "passed", "Windows supported")
+    return HealthCheckResult(
+        "os-support",
+        "warning",
+        os.name,
+        "Validate browser paths and runtime behavior on this operating system.",
+    )
+
+
+def check_chromium_presence() -> HealthCheckResult:
+    locations = [
+        Path.home() / "AppData" / "Local" / "ms-playwright",
+        Path.home() / ".cache" / "ms-playwright",
+    ]
+    for playwright_cache in locations:
+        if playwright_cache.exists():
+            return HealthCheckResult("chromium-installed", "passed", str(playwright_cache))
+    return HealthCheckResult(
+        "chromium-installed",
+        "warning",
+        "Chromium cache not found",
+        "Run `npx playwright install chromium` and `python -m playwright install chromium` if needed.",
+    )

package/python/agent_portal/exceptions.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+
+class AgentPortalError(Exception):
+    def __init__(
+        self,
+        message: str,
+        *,
+        module: str,
+        likely_cause: str,
+        suggested_fix: str,
+        can_continue: bool,
+    ) -> None:
+        super().__init__(message)
+        self.module = module
+        self.likely_cause = likely_cause
+        self.suggested_fix = suggested_fix
+        self.can_continue = can_continue
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "message": str(self),
+            "module": self.module,
+            "likelyCause": self.likely_cause,
+            "suggestedFix": self.suggested_fix,
+            "canContinue": self.can_continue,
+        }
+
+
+class RuntimeStartupError(AgentPortalError):
+    pass
+
+
+class BrowserOperationError(AgentPortalError):
+    pass
+
+
+class PolicyBlockedError(AgentPortalError):
+    pass

package/python/agent_portal/logging_utils.py

@@ -0,0 +1,33 @@
+from __future__ import annotations
+
+import json
+import logging
+import sys
+from datetime import datetime, timezone
+
+
+class JsonFormatter(logging.Formatter):
+    def format(self, record: logging.LogRecord) -> str:
+        payload = {
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "level": record.levelname,
+            "logger": record.name,
+            "message": record.getMessage(),
+        }
+        if hasattr(record, "context"):
+            payload["context"] = getattr(record, "context")
+        return json.dumps(payload)
+
+
+def build_logger(name: str, level: str = "INFO") -> logging.Logger:
+    logger = logging.getLogger(name)
+    if logger.handlers:
+        logger.setLevel(level.upper())
+        return logger
+
+    logger.setLevel(level.upper())
+    handler = logging.StreamHandler(sys.stdout)
+    handler.setFormatter(JsonFormatter())
+    logger.addHandler(handler)
+    logger.propagate = False
+    return logger