agent-portal-2 0.1.0

package/packages/agent-portal-mcp/agent_portal_mcp/doctor.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import importlib.util
+import sys
+from dataclasses import dataclass, field
+from typing import Literal
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient, RuntimeClientError
+from agent_portal_mcp.tool_registry import build_tool_registry
+
+
+@dataclass(slots=True)
+class DoctorCheck:
+    name: str
+    status: Literal["passed", "warning", "failed"]
+    details: str
+    suggested_fix: str | None = None
+
+
+@dataclass(slots=True)
+class DoctorResult:
+    checks: list[DoctorCheck] = field(default_factory=list)
+
+
+def run_doctor(runtime_url: str = "http://127.0.0.1:8765") -> DoctorResult:
+    result = DoctorResult()
+    result.checks.append(_check_python_version())
+    result.checks.append(_check_package_installed())
+    result.checks.append(_check_localhost_binding(runtime_url))
+    result.checks.append(_check_tools_registered())
+    result.checks.append(_check_runtime(runtime_url))
+    return result
+
+
+def _check_python_version() -> DoctorCheck:
+    if sys.version_info >= (3, 10):
+        return DoctorCheck("python-version", "passed", sys.version.split()[0])
+    return DoctorCheck("python-version", "failed", sys.version.split()[0], "Use Python 3.10 or newer.")
+
+
+def _check_package_installed() -> DoctorCheck:
+    if importlib.util.find_spec("agent_portal_mcp") is not None:
+        return DoctorCheck("mcp-package", "passed", "Installed")
+    return DoctorCheck("mcp-package", "warning", "Not installed into current environment", "Install with `pip install -e ./packages/agent-portal-mcp`.")
+
+
+def _check_localhost_binding(runtime_url: str) -> DoctorCheck:
+    if runtime_url.startswith("http://127.0.0.1") or runtime_url.startswith("http://localhost"):
+        return DoctorCheck("localhost-binding", "passed", runtime_url)
+    return DoctorCheck("localhost-binding", "warning", runtime_url, "Prefer localhost-only runtime URLs for MCP usage.")
+
+
+def _check_tools_registered() -> DoctorCheck:
+    count = len(build_tool_registry())
+    return DoctorCheck("tool-registry", "passed", f"{count} tools registered")
+
+
+def _check_runtime(runtime_url: str) -> DoctorCheck:
+    client = AgentPortalRuntimeClient(runtime_url=runtime_url)
+    try:
+        health = client.health()
+    except RuntimeClientError:
+        return DoctorCheck(
+            "runtime-reachable",
+            "failed",
+            runtime_url,
+            "Agent Portal runtime is not running. Start it with: agent-portal start",
+        )
+
+    version = str(health.get("runtimeVersion", "unknown"))
+    return DoctorCheck("runtime-reachable", "passed", f"{runtime_url} (runtime {version})")

package/packages/agent-portal-mcp/agent_portal_mcp/schemas/__init__.py

@@ -0,0 +1 @@
+__all__ = []

package/packages/agent-portal-mcp/agent_portal_mcp/schemas/actions.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from .risk import RiskLevel
+
+
+@dataclass(slots=True)
+class McpAction:
+    tool: str
+    runtime_action_type: str
+    reason: str
+    target: str | None = None
+    payload: str | None = None
+    risk_hint: RiskLevel = "low"
+    metadata: dict[str, Any] = field(default_factory=dict)

package/packages/agent-portal-mcp/agent_portal_mcp/schemas/results.py

@@ -0,0 +1,24 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from .risk import RiskLevel, ToolStatus
+
+
+@dataclass(slots=True)
+class ToolResult:
+    ok: bool
+    tool: str
+    session_id: str | None
+    action_id: str | None
+    status: ToolStatus
+    risk: RiskLevel
+    message: str
+    data: dict[str, Any] = field(default_factory=dict)
+    screenshot_before: str | None = None
+    screenshot_after: str | None = None
+    errors: list[str] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)

package/packages/agent-portal-mcp/agent_portal_mcp/schemas/risk.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from typing import Literal
+
+
+RiskLevel = Literal["safe", "low", "medium", "high", "blocked"]
+ToolStatus = Literal[
+    "completed",
+    "pending_approval",
+    "rejected",
+    "blocked",
+    "failed",
+]
+
+
+RISK_ORDER: list[RiskLevel] = ["safe", "low", "medium", "high", "blocked"]
+
+
+def compare_risk(left: RiskLevel, right: RiskLevel) -> int:
+    return RISK_ORDER.index(left) - RISK_ORDER.index(right)

package/packages/agent-portal-mcp/agent_portal_mcp/security/__init__.py

@@ -0,0 +1 @@
+__all__ = []

package/packages/agent-portal-mcp/agent_portal_mcp/security/policy.py

@@ -0,0 +1,27 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from agent_portal_mcp.schemas.risk import RiskLevel, compare_risk
+
+
+@dataclass(slots=True)
+class RuntimePolicySnapshot:
+    mode: str = "assisted"
+    approval_threshold: RiskLevel = "medium"
+    read_only: bool = False
+
+
+class McpPolicy:
+    def should_auto_execute(self, risk: RiskLevel, snapshot: RuntimePolicySnapshot) -> bool:
+        if risk == "blocked":
+            return False
+        if risk == "high":
+            return False
+        if snapshot.read_only and risk != "safe":
+            return False
+        if compare_risk(risk, snapshot.approval_threshold) >= 0 and risk != "safe":
+            return False
+        if snapshot.mode not in {"assisted", "autonomous", "manual-override", "read-only"}:
+            return False
+        return True

package/packages/agent-portal-mcp/agent_portal_mcp/server.py

@@ -0,0 +1,148 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import asdict
+from typing import Any
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient, RuntimeClientError
+from agent_portal_mcp.schemas.results import ToolResult
+from agent_portal_mcp.tool_registry import ToolDefinition, build_tool_registry
+
+
+class AgentPortalMcpServer:
+    def __init__(self, runtime_url: str = "http://127.0.0.1:8765") -> None:
+        self.client = AgentPortalRuntimeClient(runtime_url=runtime_url)
+        self.tools = build_tool_registry()
+
+    def serve_stdio(self) -> None:
+        while True:
+            payload = self._read_message()
+            if payload is None:
+                return
+            response = self.handle_request(payload)
+            if response is not None:
+                self._write_message(response)
+
+    def handle_request(self, payload: dict[str, Any]) -> dict[str, Any] | None:
+        method = payload.get("method")
+        request_id = payload.get("id")
+
+        if method == "notifications/initialized":
+            return None
+        if method == "initialize":
+            return self._jsonrpc(
+                request_id,
+                {
+                    "protocolVersion": "2024-11-05",
+                    "capabilities": {"tools": {"listChanged": False}},
+                    "serverInfo": {"name": "agent-portal-mcp", "version": "0.0.2"},
+                },
+            )
+        if method == "ping":
+            return self._jsonrpc(request_id, {})
+        if method == "tools/list":
+            return self._jsonrpc(
+                request_id,
+                {
+                    "tools": [
+                        {
+                            "name": tool.name,
+                            "description": tool.description,
+                            "inputSchema": tool.input_schema,
+                        }
+                        for tool in self.tools.values()
+                    ]
+                },
+            )
+        if method == "tools/call":
+            params = payload.get("params", {})
+            name = str(params.get("name", ""))
+            arguments = params.get("arguments", {})
+            if not isinstance(arguments, dict):
+                arguments = {}
+            result = self.call_tool(name, arguments)
+            return self._jsonrpc(
+                request_id,
+                {
+                    "content": [{"type": "text", "text": json.dumps(result.to_dict(), indent=2)}],
+                    "structuredContent": result.to_dict(),
+                    "isError": not result.ok,
+                },
+            )
+
+        return self._error(request_id, -32601, f"Method not found: {method}")
+
+    def call_tool(self, name: str, arguments: dict[str, Any]) -> ToolResult:
+        definition = self.tools.get(name)
+        if definition is None:
+            return ToolResult(
+                ok=False,
+                tool=name,
+                session_id=None,
+                action_id=None,
+                status="failed",
+                risk="blocked",
+                message=f"Unknown MCP tool: {name}",
+                errors=[f"Tool `{name}` is not registered."],
+            )
+
+        try:
+            return definition.handler(self.client, arguments)
+        except RuntimeClientError as exc:
+            return ToolResult(
+                ok=False,
+                tool=name,
+                session_id=None,
+                action_id=None,
+                status="failed",
+                risk="blocked",
+                message=str(exc),
+                errors=[str(exc)],
+            )
+        except Exception as exc:
+            return ToolResult(
+                ok=False,
+                tool=name,
+                session_id=None,
+                action_id=None,
+                status="failed",
+                risk="blocked",
+                message="MCP tool execution failed.",
+                errors=[self._redact(str(exc))],
+            )
+
+    def _read_message(self) -> dict[str, Any] | None:
+        headers: dict[str, str] = {}
+        while True:
+            line = sys.stdin.buffer.readline()
+            if not line:
+                return None
+            if line in {b"\r\n", b"\n"}:
+                break
+            key, value = line.decode("utf8").split(":", 1)
+            headers[key.strip().lower()] = value.strip()
+
+        length = int(headers.get("content-length", "0"))
+        if length <= 0:
+            return None
+        body = sys.stdin.buffer.read(length)
+        return json.loads(body.decode("utf8"))
+
+    def _write_message(self, payload: dict[str, Any]) -> None:
+        encoded = json.dumps(payload).encode("utf8")
+        sys.stdout.buffer.write(f"Content-Length: {len(encoded)}\r\n\r\n".encode("utf8"))
+        sys.stdout.buffer.write(encoded)
+        sys.stdout.buffer.flush()
+
+    def _jsonrpc(self, request_id: Any, result: dict[str, Any]) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": request_id, "result": result}
+
+    def _error(self, request_id: Any, code: int, message: str) -> dict[str, Any]:
+        return {"jsonrpc": "2.0", "id": request_id, "error": {"code": code, "message": message}}
+
+    def _redact(self, value: str) -> str:
+        token = self.client.token
+        if token:
+            return value.replace(token, "[REDACTED]")
+        return value

package/packages/agent-portal-mcp/agent_portal_mcp/tool_registry.py

@@ -0,0 +1,58 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Callable
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient
+from agent_portal_mcp.schemas.results import ToolResult
+from agent_portal_mcp.tools import browser, inspection, navigation, reports, steering
+
+
+ToolHandler = Callable[[AgentPortalRuntimeClient, dict[str, Any]], ToolResult]
+
+
+@dataclass(slots=True)
+class ToolDefinition:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    handler: ToolHandler
+
+
+def build_tool_registry() -> dict[str, ToolDefinition]:
+    definitions = [
+        ToolDefinition("browser_open", "Open a browser URL through Agent Portal.", {"type": "object", "properties": {"url": {"type": "string"}, "reason": {"type": "string"}}, "required": ["url"]}, browser.browser_open),
+        ToolDefinition("browser_close", "Close the current browser session.", {"type": "object", "properties": {"reason": {"type": "string"}}}, browser.browser_close),
+        ToolDefinition("browser_refresh", "Refresh the current page.", {"type": "object", "properties": {"reason": {"type": "string"}}}, browser.browser_refresh),
+        ToolDefinition("browser_back", "Navigate backward in history.", {"type": "object", "properties": {"reason": {"type": "string"}}}, browser.browser_back),
+        ToolDefinition("browser_forward", "Navigate forward in history.", {"type": "object", "properties": {"reason": {"type": "string"}}}, browser.browser_forward),
+        ToolDefinition("browser_status", "Return browser session status.", {"type": "object", "properties": {}}, browser.browser_status),
+        ToolDefinition("navigate_to_url", "Navigate to a URL through the runtime.", {"type": "object", "properties": {"url": {"type": "string"}, "reason": {"type": "string"}}, "required": ["url"]}, navigation.navigate_to_url),
+        ToolDefinition("click_element", "Click an element selected by CSS, role text, or label.", {"type": "object", "properties": {"selector": {"type": "string"}, "reason": {"type": "string"}}, "required": ["selector"]}, navigation.click_element),
+        ToolDefinition("type_text", "Type text into an input element.", {"type": "object", "properties": {"selector": {"type": "string"}, "text": {"type": "string"}, "reason": {"type": "string"}}, "required": ["selector", "text"]}, navigation.type_text),
+        ToolDefinition("scroll_page", "Scroll the page or bring an element into view.", {"type": "object", "properties": {"selector": {"type": "string"}, "reason": {"type": "string"}}}, navigation.scroll_page),
+        ToolDefinition("hover_element", "Hover over an element.", {"type": "object", "properties": {"selector": {"type": "string"}, "reason": {"type": "string"}}, "required": ["selector"]}, navigation.hover_element),
+        ToolDefinition("wait_for_page", "Wait for a page element to appear.", {"type": "object", "properties": {"selector": {"type": "string"}, "reason": {"type": "string"}}, "required": ["selector"]}, navigation.wait_for_page),
+        ToolDefinition("capture_screenshot", "Capture a screenshot with evidence metadata.", {"type": "object", "properties": {"label": {"type": "string"}}}, inspection.capture_screenshot),
+        ToolDefinition("read_page_text", "Read visible text from an element.", {"type": "object", "properties": {"selector": {"type": "string"}, "reason": {"type": "string"}}, "required": ["selector"]}, inspection.read_page_text),
+        ToolDefinition("read_dom", "Read the current page DOM.", {"type": "object", "properties": {}}, inspection.read_dom),
+        ToolDefinition("read_accessibility_tree", "Read the page accessibility tree.", {"type": "object", "properties": {}}, inspection.read_accessibility_tree),
+        ToolDefinition("read_console_errors", "Read collected console errors.", {"type": "object", "properties": {}}, inspection.read_console_errors),
+        ToolDefinition("read_network_failures", "Read collected network failures.", {"type": "object", "properties": {}}, inspection.read_network_failures),
+        ToolDefinition("inspect_element", "Inspect a specific element.", {"type": "object", "properties": {"selector": {"type": "string"}}, "required": ["selector"]}, inspection.inspect_element),
+        ToolDefinition("propose_action", "Propose an action through the runtime policy engine.", {"type": "object", "properties": {"action_type": {"type": "string"}, "target": {"type": "string"}, "payload": {"type": "string"}, "reason": {"type": "string"}, "risk": {"type": "string"}}, "required": ["action_type", "reason"]}, steering.propose_action),
+        ToolDefinition("approve_action", "Approve and optionally execute a queued action.", {"type": "object", "properties": {"action_id": {"type": "string"}, "execute": {"type": "boolean"}}, "required": ["action_id"]}, steering.approve_action),
+        ToolDefinition("reject_action", "Reject a queued action.", {"type": "object", "properties": {"action_id": {"type": "string"}, "reason": {"type": "string"}}, "required": ["action_id"]}, steering.reject_action),
+        ToolDefinition("pause_agent", "Pause the agent runtime.", {"type": "object", "properties": {}}, steering.pause_agent),
+        ToolDefinition("resume_agent", "Resume the agent runtime.", {"type": "object", "properties": {}}, steering.resume_agent),
+        ToolDefinition("stop_agent", "Stop the agent runtime.", {"type": "object", "properties": {}}, steering.stop_agent),
+        ToolDefinition("set_goal", "Set the current runtime goal.", {"type": "object", "properties": {"goal": {"type": "string"}}, "required": ["goal"]}, steering.set_goal),
+        ToolDefinition("get_current_goal", "Get the current runtime goal.", {"type": "object", "properties": {}}, steering.get_current_goal),
+        ToolDefinition("get_action_queue", "Get the runtime action queue.", {"type": "object", "properties": {}}, steering.get_action_queue),
+        ToolDefinition("set_action_mode", "Set the runtime action mode.", {"type": "object", "properties": {"mode": {"type": "string"}}, "required": ["mode"]}, steering.set_action_mode),
+        ToolDefinition("generate_report", "Generate a runtime report.", {"type": "object", "properties": {}}, reports.generate_report),
+        ToolDefinition("list_reports", "List available runtime reports.", {"type": "object", "properties": {}}, reports.list_reports),
+        ToolDefinition("read_report", "Read a report by name.", {"type": "object", "properties": {"report": {"type": "string"}}, "required": ["report"]}, reports.read_report),
+        ToolDefinition("export_report", "Export a report to a destination path.", {"type": "object", "properties": {"report": {"type": "string"}, "destination": {"type": "string"}}, "required": ["report"]}, reports.export_report),
+    ]
+    return {definition.name: definition for definition in definitions}

package/packages/agent-portal-mcp/agent_portal_mcp/tools/__init__.py

@@ -0,0 +1 @@
+__all__ = []

package/packages/agent-portal-mcp/agent_portal_mcp/tools/browser.py

@@ -0,0 +1,89 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient
+from agent_portal_mcp.schemas.actions import McpAction
+from agent_portal_mcp.schemas.results import ToolResult
+from agent_portal_mcp.tools.common import build_result, execute_or_queue
+
+
+def browser_open(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    return execute_or_queue(
+        client,
+        "browser_open",
+        McpAction(
+            tool="browser_open",
+            runtime_action_type="open_url",
+            reason=str(args.get("reason", "Open browser URL")),
+            target=str(args.get("url", "")),
+            risk_hint="low",
+        ),
+        lambda _: {"url": args.get("url")},
+    )
+
+
+def browser_close(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    return execute_or_queue(
+        client,
+        "browser_close",
+        McpAction(
+            tool="browser_close",
+            runtime_action_type="browser_close",
+            reason=str(args.get("reason", "Close browser session")),
+            risk_hint="medium",
+        ),
+    )
+
+
+def browser_refresh(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    return execute_or_queue(
+        client,
+        "browser_refresh",
+        McpAction(
+            tool="browser_refresh",
+            runtime_action_type="browser_refresh",
+            reason=str(args.get("reason", "Refresh current page")),
+            risk_hint="low",
+        ),
+    )
+
+
+def browser_back(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    return execute_or_queue(
+        client,
+        "browser_back",
+        McpAction(
+            tool="browser_back",
+            runtime_action_type="browser_back",
+            reason=str(args.get("reason", "Navigate backward")),
+            risk_hint="low",
+        ),
+    )
+
+
+def browser_forward(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    return execute_or_queue(
+        client,
+        "browser_forward",
+        McpAction(
+            tool="browser_forward",
+            runtime_action_type="browser_forward",
+            reason=str(args.get("reason", "Navigate forward")),
+            risk_hint="low",
+        ),
+    )
+
+
+def browser_status(client: AgentPortalRuntimeClient, _args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    browser = client.browser_status()
+    return build_result(
+        "browser_status",
+        status,
+        None,
+        "completed",
+        "safe",
+        "Returned browser status.",
+        {"browser": browser},
+    )

package/packages/agent-portal-mcp/agent_portal_mcp/tools/common.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient
+from agent_portal_mcp.schemas.actions import McpAction
+from agent_portal_mcp.schemas.results import ToolResult
+from agent_portal_mcp.schemas.risk import RiskLevel
+from agent_portal_mcp.security.policy import McpPolicy, RuntimePolicySnapshot
+
+
+def runtime_policy_snapshot(status_payload: dict[str, Any]) -> RuntimePolicySnapshot:
+    policy = status_payload.get("policy", {})
+    return RuntimePolicySnapshot(
+        mode=str(policy.get("mode", "assisted")),
+        approval_threshold=str(policy.get("approval_threshold", "medium")),  # type: ignore[arg-type]
+        read_only=bool(policy.get("read_only", False)),
+    )
+
+
+def build_result(
+    tool: str,
+    status_payload: dict[str, Any],
+    action_payload: dict[str, Any] | None,
+    status: str,
+    risk: RiskLevel,
+    message: str,
+    data: dict[str, Any] | None = None,
+    errors: list[str] | None = None,
+) -> ToolResult:
+    session = status_payload.get("session", {})
+    return ToolResult(
+        ok=status == "completed",
+        tool=tool,
+        session_id=session.get("session_id"),
+        action_id=action_payload.get("action_id") if action_payload else None,
+        status=status,  # type: ignore[arg-type]
+        risk=risk,
+        message=message,
+        data=data or {},
+        screenshot_before=action_payload.get("before_screenshot") if action_payload else None,
+        screenshot_after=action_payload.get("after_screenshot") if action_payload else None,
+        errors=errors or [],
+    )
+
+
+def execute_or_queue(
+    client: AgentPortalRuntimeClient,
+    tool: str,
+    action: McpAction,
+    data_builder: Callable[[dict[str, Any] | None], dict[str, Any]] | None = None,
+) -> ToolResult:
+    status_payload = client.status()
+    proposed = client.propose_action(
+        action.runtime_action_type,
+        action.reason,
+        target=action.target,
+        payload=action.payload,
+        risk_level=action.risk_hint,
+    )
+    risk = str(proposed.get("risk_level", action.risk_hint))  # type: ignore[assignment]
+    policy = McpPolicy()
+    snapshot = runtime_policy_snapshot(status_payload)
+
+    if proposed.get("status") == "blocked":
+        return build_result(
+            tool,
+            status_payload,
+            proposed,
+            "blocked",
+            risk,  # type: ignore[arg-type]
+            "Action was blocked by the Agent Portal runtime policy engine.",
+            data_builder(proposed) if data_builder else {},
+            [str(proposed.get("result") or "blocked")],
+        )
+
+    if not policy.should_auto_execute(risk, snapshot):  # type: ignore[arg-type]
+        return build_result(
+            tool,
+            status_payload,
+            proposed,
+            "pending_approval",
+            risk,  # type: ignore[arg-type]
+            "Action entered the approval queue.",
+            data_builder(proposed) if data_builder else {},
+        )
+
+    completed = client.approve_action(str(proposed.get("action_id", "")), execute=True)
+    fresh_status = client.status()
+    return build_result(
+        tool,
+        fresh_status,
+        completed,
+        "completed",
+        risk,  # type: ignore[arg-type]
+        "Action executed through the Agent Portal runtime.",
+        data_builder(completed) if data_builder else {},
+    )

package/packages/agent-portal-mcp/agent_portal_mcp/tools/inspection.py

@@ -0,0 +1,93 @@
+from __future__ import annotations
+
+from typing import Any
+
+from agent_portal_mcp.bridge.runtime_client import AgentPortalRuntimeClient
+from agent_portal_mcp.schemas.results import ToolResult
+from agent_portal_mcp.tools.common import build_result
+
+
+def capture_screenshot(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.capture(str(args.get("label", "mcp-capture")))
+    action = payload.get("action", {})
+    return build_result(
+        "capture_screenshot",
+        status,
+        action if isinstance(action, dict) else None,
+        "completed",
+        "safe",
+        "Captured screenshot.",
+        payload,
+    )
+
+
+def read_page_text(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.read_text(
+        str(args.get("selector", "body")),
+        str(args.get("reason", "Read page text")),
+    )
+    return build_result("read_page_text", status, payload.get("action"), "completed", "safe", "Read page text.", payload)
+
+
+def read_dom(client: AgentPortalRuntimeClient, _args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.read_dom()
+    return build_result("read_dom", status, None, "completed", "safe", "Read page DOM.", payload)
+
+
+def read_accessibility_tree(client: AgentPortalRuntimeClient, _args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.read_accessibility_tree()
+    return build_result(
+        "read_accessibility_tree",
+        status,
+        None,
+        "completed",
+        "safe",
+        "Read accessibility tree.",
+        payload,
+    )
+
+
+def read_console_errors(client: AgentPortalRuntimeClient, _args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.read_console_errors()
+    return build_result(
+        "read_console_errors",
+        status,
+        None,
+        "completed",
+        "safe",
+        "Read console errors.",
+        payload,
+    )
+
+
+def read_network_failures(client: AgentPortalRuntimeClient, _args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.read_network_failures()
+    return build_result(
+        "read_network_failures",
+        status,
+        None,
+        "completed",
+        "safe",
+        "Read network failures.",
+        payload,
+    )
+
+
+def inspect_element(client: AgentPortalRuntimeClient, args: dict[str, Any]) -> ToolResult:
+    status = client.status()
+    payload = client.inspect_element(str(args.get("selector", "")))
+    return build_result(
+        "inspect_element",
+        status,
+        None,
+        "completed",
+        "safe",
+        "Inspected element.",
+        payload,
+    )