agent-portal 0.0.2__tar.gz

agent_portal-0.0.2/PKG-INFO

@@ -0,0 +1,32 @@
+Metadata-Version: 2.4
+Name: agent-portal
+Version: 0.0.2
+Summary: Python runtime package for Agent Portal.
+Author: Magnexis
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-Expression: MIT
+Requires-Dist: playwright>=1.54.0
+Project-URL: Homepage, https://github.com/magnexis/agent-portal
+Project-URL: Issues, https://github.com/magnexis/agent-portal/issues
+Project-URL: Repository, https://github.com/magnexis/agent-portal.git
+
+# Agent Portal Python Runtime
+
+This package contains the local Agent Portal runtime.
+
+It provides:
+
+- the local HTTP runtime server
+- Playwright-backed browser control
+- agent steering and action policy enforcement
+- runtime doctor checks
+- report generation
+- plugin manifest discovery and validation
+
+Install locally with:
+
+```bash
+pip install -e ./python
+```
+

agent_portal-0.0.2/README.md

@@ -0,0 +1,18 @@
+# Agent Portal Python Runtime
+
+This package contains the local Agent Portal runtime.
+
+It provides:
+
+- the local HTTP runtime server
+- Playwright-backed browser control
+- agent steering and action policy enforcement
+- runtime doctor checks
+- report generation
+- plugin manifest discovery and validation
+
+Install locally with:
+
+```bash
+pip install -e ./python
+```

agent_portal-0.0.2/agent_portal/__init__.py

@@ -0,0 +1,3 @@
+from .runtime import PortalRuntime
+
+__all__ = ["PortalRuntime"]

agent_portal-0.0.2/agent_portal/__main__.py

@@ -0,0 +1,5 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    main()

agent_portal-0.0.2/agent_portal/browser.py

@@ -0,0 +1,393 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from .exceptions import BrowserOperationError
+from .logging_utils import build_logger
+
+
+class BrowserController:
+    def __init__(self, screenshot_directory: Path, timeout_ms: int = 5_000) -> None:
+        self.screenshot_directory = screenshot_directory
+        self.timeout_ms = timeout_ms
+        self._page = None
+        self._browser = None
+        self._context = None
+        self._playwright = None
+        self._console_errors: list[str] = []
+        self._network_errors: list[str] = []
+        self.logger = build_logger("agent_portal.browser")
+
+    def available(self) -> bool:
+        try:
+            import playwright.sync_api  # noqa: F401
+            return True
+        except Exception:
+            return False
+
+    def start(self) -> None:
+        if self._page is not None:
+            return
+
+        try:
+            from playwright.sync_api import sync_playwright
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Python Playwright is not installed.",
+                module="agent_portal.browser",
+                likely_cause="The Python runtime dependencies have not been installed.",
+                suggested_fix="Run `pip install -e ./python`.",
+                can_continue=False,
+            ) from exc
+
+        try:
+            self._playwright = sync_playwright().start()
+            self._browser = self._playwright.chromium.launch(headless=True)
+            self._context = self._browser.new_context()
+            self._page = self._context.new_page()
+            self._page.set_default_timeout(self.timeout_ms)
+            self._page.on("console", self._handle_console_message)
+            self._page.on("pageerror", self._handle_page_error)
+            self._page.on("requestfailed", self._handle_request_failed)
+            self.logger.info("Browser session started")
+        except Exception as exc:
+            self.stop()
+            raise BrowserOperationError(
+                "Browser failed to launch because Chromium is not installed or not available.",
+                module="agent_portal.browser",
+                likely_cause="Playwright Chromium is missing or corrupted.",
+                suggested_fix="Run `python -m playwright install chromium`.",
+                can_continue=False,
+            ) from exc
+
+    def stop(self) -> None:
+        if self._context is not None:
+            self._context.close()
+        if self._browser is not None:
+            self._browser.close()
+        if self._playwright is not None:
+            self._playwright.stop()
+        self._browser = None
+        self._context = None
+        self._page = None
+        self._playwright = None
+        self._console_errors = []
+        self._network_errors = []
+
+    def open_url(self, url: str) -> None:
+        page = self._require_page()
+        try:
+            page.goto(url, wait_until="domcontentloaded", timeout=self.timeout_ms)
+            page.wait_for_load_state("networkidle", timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Failed to open `{url}`.",
+                module="agent_portal.browser",
+                likely_cause="The page did not finish loading, the dev server is down, or navigation timed out.",
+                suggested_fix="Verify the target URL is reachable and increase the browser timeout if the app is slow.",
+                can_continue=True,
+            ) from exc
+
+    def close_page(self) -> None:
+        self.stop()
+
+    def refresh(self) -> None:
+        page = self._require_page()
+        try:
+            page.reload(wait_until="domcontentloaded", timeout=self.timeout_ms)
+            page.wait_for_load_state("networkidle", timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Page refresh failed.",
+                module="agent_portal.browser",
+                likely_cause="The page became unavailable or reload timed out.",
+                suggested_fix="Verify the page is reachable and retry the refresh.",
+                can_continue=True,
+            ) from exc
+
+    def back(self) -> None:
+        page = self._require_page()
+        try:
+            page.go_back(wait_until="domcontentloaded", timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Browser back navigation failed.",
+                module="agent_portal.browser",
+                likely_cause="There is no prior history entry or the navigation failed.",
+                suggested_fix="Open a page first or verify browser history before retrying.",
+                can_continue=True,
+            ) from exc
+
+    def forward(self) -> None:
+        page = self._require_page()
+        try:
+            page.go_forward(wait_until="domcontentloaded", timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Browser forward navigation failed.",
+                module="agent_portal.browser",
+                likely_cause="There is no forward history entry or the navigation failed.",
+                suggested_fix="Navigate backward before trying to move forward again.",
+                can_continue=True,
+            ) from exc
+
+    def screenshot(self, name: str) -> str:
+        page = self._require_page()
+        self.screenshot_directory.mkdir(parents=True, exist_ok=True)
+        file_path = self.screenshot_directory / f"{name}.png"
+        try:
+            page.screenshot(path=str(file_path), full_page=True)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Screenshot capture failed.",
+                module="agent_portal.browser",
+                likely_cause="The page crashed or the screenshot path is not writable.",
+                suggested_fix="Check browser health and filesystem permissions for the screenshot directory.",
+                can_continue=True,
+            ) from exc
+        return str(file_path)
+
+    def click(self, selector: str) -> None:
+        locator = self._resolve_locator(selector)
+        self._ensure_actionable(locator, selector)
+        try:
+            locator.click(timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Click failed for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The element is covered, detached, or the page is still changing.",
+                suggested_fix="Wait for the element to stabilize or use a more specific selector.",
+                can_continue=True,
+            ) from exc
+
+    def type_text(self, selector: str, value: str) -> None:
+        locator = self._resolve_locator(selector)
+        self._ensure_actionable(locator, selector)
+        try:
+            locator.fill(value, timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Typing failed for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The target is read-only, disabled, or not a fillable element.",
+                suggested_fix="Use an input selector that resolves to a visible text field.",
+                can_continue=True,
+            ) from exc
+
+    def hover(self, selector: str) -> None:
+        locator = self._resolve_locator(selector)
+        self._ensure_actionable(locator, selector)
+        try:
+            locator.hover(timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Hover failed for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The element is hidden or no longer attached to the page.",
+                suggested_fix="Wait for the element to become visible before hovering.",
+                can_continue=True,
+            ) from exc
+
+    def scroll(self, selector: str | None = None) -> None:
+        page = self._require_page()
+        try:
+            if selector:
+                self._resolve_locator(selector).scroll_into_view_if_needed(timeout=self.timeout_ms)
+                return
+            page.mouse.wheel(0, 800)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Scroll failed.",
+                module="agent_portal.browser",
+                likely_cause="The page is not interactive or the target element no longer exists.",
+                suggested_fix="Retry after the page settles or scroll the main page instead of a stale element.",
+                can_continue=True,
+            ) from exc
+
+    def wait(self, selector: str) -> None:
+        try:
+            self._resolve_locator(selector).wait_for(state="visible", timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Wait timed out for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The element never became visible or the selector is incorrect.",
+                suggested_fix="Use a more stable selector or increase the browser timeout for slower pages.",
+                can_continue=True,
+            ) from exc
+
+    def inspect(self) -> dict[str, Any]:
+        page = self._require_page()
+        return {
+            "url": page.url,
+            "title": page.title(),
+            "dom": page.content(),
+            "accessibilityTree": self.read_accessibility_tree(),
+            "consoleErrors": self.read_console(),
+            "networkErrors": self.read_network(),
+        }
+
+    def current_url(self) -> str | None:
+        return self._page.url if self._page else None
+
+    def current_title(self) -> str | None:
+        return self._page.title() if self._page else None
+
+    def read_console(self) -> list[str]:
+        return list(self._console_errors)
+
+    def read_network(self) -> list[str]:
+        return list(self._network_errors)
+
+    def read_dom(self) -> str:
+        return self._require_page().content()
+
+    def read_accessibility_tree(self) -> Any:
+        page = self._require_page()
+        accessibility = getattr(page, "accessibility", None)
+        if accessibility is None:
+            return None
+        try:
+            return accessibility.snapshot()
+        except Exception:
+            return None
+
+    def read_text(self, selector: str) -> str | None:
+        locator = self._resolve_locator(selector)
+        try:
+            return locator.text_content(timeout=self.timeout_ms)
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Failed to read text for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The target no longer exists or text content could not be resolved.",
+                suggested_fix="Target a stable visible element and retry.",
+                can_continue=True,
+            ) from exc
+
+    def execute(self, script: str) -> Any:
+        page = self._require_page()
+        try:
+            return page.evaluate(script)
+        except Exception as exc:
+            raise BrowserOperationError(
+                "Script execution failed.",
+                module="agent_portal.browser",
+                likely_cause="The script threw an error or referenced unavailable browser state.",
+                suggested_fix="Validate the script against the current page and retry with a simpler expression.",
+                can_continue=True,
+            ) from exc
+
+    def inspect_element(self, selector: str) -> dict[str, Any]:
+        locator = self._resolve_locator(selector)
+        try:
+            text = locator.text_content(timeout=self.timeout_ms)
+            html = locator.evaluate("(node) => node.outerHTML")
+            is_visible = locator.is_visible()
+            return {
+                "selector": selector,
+                "text": text,
+                "html": html,
+                "visible": is_visible,
+            }
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Element inspection failed for `{selector}`.",
+                module="agent_portal.browser",
+                likely_cause="The element became detached or could not be serialized.",
+                suggested_fix="Retry with a more specific selector after the page settles.",
+                can_continue=True,
+            ) from exc
+
+    def _resolve_locator(self, selector: str):
+        page = self._require_page()
+        candidates = [selector]
+        normalized = selector.lstrip("#")
+        candidates.extend(
+            [
+                f"#{normalized}",
+                f"[name='{normalized}']",
+                f"[aria-label='{normalized}']",
+                f"text={normalized}",
+            ]
+        )
+        for candidate in candidates:
+            locator = page.locator(candidate).first
+            try:
+                if locator.count() > 0:
+                    return locator
+            except Exception:
+                continue
+        lowered = normalized.lower()
+        try:
+            role_candidates = [
+                page.get_by_role("button", name=normalized).first,
+                page.get_by_role("link", name=normalized).first,
+                page.get_by_role("textbox", name=normalized).first,
+            ]
+            for locator in role_candidates:
+                if locator.count() > 0:
+                    return locator
+            if lowered.startswith("//"):
+                xpath_locator = page.locator(f"xpath={selector}").first
+                if xpath_locator.count() > 0:
+                    return xpath_locator
+        except Exception:
+            pass
+        raise BrowserOperationError(
+            f"Element could not be found for selector `{selector}`.",
+            module="agent_portal.browser",
+            likely_cause="The selector is stale, hidden, or never existed on the page.",
+            suggested_fix="Try a more specific selector, aria-label, visible text, or role target.",
+            can_continue=True,
+        )
+
+    def _ensure_actionable(self, locator: Any, selector: str) -> None:
+        try:
+            locator.wait_for(state="visible", timeout=self.timeout_ms)
+            if locator.is_disabled():
+                raise BrowserOperationError(
+                    f"Element `{selector}` is disabled.",
+                    module="agent_portal.browser",
+                    likely_cause="The control is present but not interactive yet.",
+                    suggested_fix="Wait for the app to finish loading or target an enabled element.",
+                    can_continue=True,
+                )
+        except BrowserOperationError:
+            raise
+        except Exception as exc:
+            raise BrowserOperationError(
+                f"Element `{selector}` is not actionable.",
+                module="agent_portal.browser",
+                likely_cause="The target is hidden, detached, or blocked by a modal.",
+                suggested_fix="Retry after the page settles or target a visible element inside the active dialog.",
+                can_continue=True,
+            ) from exc
+
+    def _require_page(self):
+        if self._page is None:
+            raise BrowserOperationError(
+                "Browser session is not ready.",
+                module="agent_portal.browser",
+                likely_cause="The runtime has not launched the browser yet.",
+                suggested_fix="Start the runtime and open a page before issuing browser actions.",
+                can_continue=False,
+            )
+        return self._page
+
+    def _handle_console_message(self, message: Any) -> None:
+        if getattr(message, "type", "") == "error":
+            self._console_errors.append(message.text)
+            self._console_errors = self._console_errors[-20:]
+
+    def _handle_page_error(self, error: Any) -> None:
+        self._console_errors.append(str(error))
+        self._console_errors = self._console_errors[-20:]
+
+    def _handle_request_failed(self, request: Any) -> None:
+        failure = request.failure
+        error_text = failure["errorText"] if isinstance(failure, dict) else "unknown failure"
+        self._network_errors.append(f"{request.method} {request.url} - {error_text}")
+        self._network_errors = self._network_errors[-20:]

agent_portal-0.0.2/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

agent_portal-0.0.2/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