agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/web_ui/web_server.py

@@ -0,0 +1,297 @@
+"""Port of operations/dev/web-ui/web-server.ts: the local web UI / API proxy server.
+
+Binds 127.0.0.1 only. Owns lifecycle, Host/Origin checks, CORS and routing; route handlers live
+in ``handlers/``. Agent servers are started on demand when the frontend selects an agent, and the
+prebuilt agent-inspector frontend is served as static files.
+"""
+
+import os
+import threading
+from collections.abc import Callable
+from concurrent.futures import Future
+from dataclasses import dataclass, field
+from importlib import resources
+from typing import Any
+from urllib.parse import parse_qs, urlsplit
+
+from agentcore.operations.dev._server import Request, Response, make_server
+from agentcore.operations.dev.config import DevConfig
+from agentcore.operations.dev.dev_server import DevServer
+from agentcore.operations.dev.web_ui.constants import WEB_UI_LOCAL_URL, AgentError, AgentInfo, HarnessInfo
+
+MIME_TYPES = {
+    ".html": "text/html",
+    ".js": "application/javascript",
+    ".css": "text/css",
+    ".map": "application/json",
+    ".svg": "image/svg+xml",
+}
+
+# CSP header to block inline script injection from malicious agent responses.
+CSP_HEADER = (
+    "default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'; connect-src 'self'; "
+    "img-src 'self' data:; font-src 'self' data:"
+)
+
+OnLog = Callable[[str, str], None]
+
+
+def resolve_ui_dist_dir() -> str | None:
+    """Frontend assets: ``AGENT_INSPECTOR_PATH`` override, else the vendored ``agentcore/agent_inspector``."""
+    candidates: list[str] = []
+    override = os.environ.get("AGENT_INSPECTOR_PATH")
+    if override:
+        candidates.append(override)
+    try:
+        candidates.append(str(resources.files("agentcore").joinpath("agent_inspector")))
+    except (ModuleNotFoundError, TypeError):
+        pass
+    for directory in candidates:
+        if os.path.exists(os.path.join(directory, "index.html")):
+            return directory
+    return None
+
+
+@dataclass
+class RunningAgent:
+    server: DevServer
+    port: int
+    protocol: str
+
+
+@dataclass
+class WebUIOptions:
+    mode: str
+    ui_port: int
+    agents: list[AgentInfo]
+    agent_base_port: int | None = None
+    harnesses: list[HarnessInfo] = field(default_factory=list)
+    get_dev_config: Callable[[str], DevConfig | None] | None = None
+    env_vars: dict[str, str] | None = None
+    get_env_vars: Callable[[], dict[str, str]] | None = None
+    config_root: str | None = None
+    on_ready: Callable[[str], None] | None = None
+    on_log: OnLog | None = None
+    on_start: Callable[[str], dict[str, Any]] | None = None
+    on_list_traces: Callable[..., dict[str, Any]] | None = None
+    on_get_trace: Callable[..., dict[str, Any]] | None = None
+    on_list_cloud_watch_traces: Callable[..., dict[str, Any]] | None = None
+    on_get_cloud_watch_trace: Callable[..., dict[str, Any]] | None = None
+    on_list_memory_records: Callable[[dict[str, Any]], dict[str, Any]] | None = None
+    on_retrieve_memory_records: Callable[[dict[str, Any]], dict[str, Any]] | None = None
+    selected_agent: str | None = None
+    selected_harness: str | None = None
+    reload_agents: Callable[[], list[AgentInfo]] | None = None
+
+
+def parse_request_url(req: Request) -> tuple[str, Callable[[str], str | None]]:
+    """``(pathname, param)`` where ``param(name)`` returns the first query value or None."""
+    parts = urlsplit(req.url or "")
+    query = parse_qs(parts.query, keep_blank_values=True)
+
+    def param(name: str) -> str | None:
+        values = query.get(name)
+        return values[0] if values else None
+
+    return parts.path, param
+
+
+class WebUIServer:
+    """Also serves as the handlers' RouteContext."""
+
+    def __init__(self, options: WebUIOptions):
+        self.options = options
+        self.running_agents: dict[str, RunningAgent] = {}
+        self.starting_agents: dict[str, Future[dict[str, Any]]] = {}
+        self.agent_errors: dict[str, AgentError] = {}
+        self.state_lock = threading.Lock()
+        self._server = None
+        self._thread: threading.Thread | None = None
+        self._watcher: threading.Thread | None = None
+        self._watch_stop = threading.Event()
+
+    # --- lifecycle --------------------------------------------------------------------------
+
+    def log(self, level: str, message: str) -> None:
+        if self.options.on_log:
+            self.options.on_log(level, message)
+
+    def start(self) -> None:
+        ui_port = self.options.ui_port
+        try:
+            self._server = make_server("127.0.0.1", ui_port, self._handle)
+        except OSError as err:
+            self.log("error", f"Web UI server error: {err}")
+            return
+        if ui_port == 0:  # ephemeral (tests): adopt the bound port so origin checks line up
+            self.options.ui_port = self._server.server_address[1]
+        self._thread = threading.Thread(target=self._server.serve_forever, daemon=True)
+        self._thread.start()
+        if self.options.on_ready:
+            self.options.on_ready(f"http://localhost:{self.options.ui_port}")
+        self._start_config_watcher()
+
+    def stop(self) -> None:
+        self._watch_stop.set()
+        for agent in list(self.running_agents.values()):
+            agent.server.kill()
+        self.running_agents.clear()
+        if self._server is not None:
+            self._server.shutdown()
+            self._server.server_close()
+            self._server = None
+
+    def _start_config_watcher(self) -> None:
+        """Poll agentcore.json for changes and reload the agents list (fs.watch equivalent)."""
+        config_root, reload_agents = self.options.config_root, self.options.reload_agents
+        if not config_root or not reload_agents:
+            return
+        config_path = os.path.join(config_root, "agentcore.json")
+        try:
+            last = os.stat(config_path).st_mtime_ns
+        except OSError as err:
+            self.log("warn", f"Could not watch agentcore.json: {err}")
+            return
+
+        def watch() -> None:
+            nonlocal last
+            while not self._watch_stop.wait(0.5):
+                try:
+                    mtime = os.stat(config_path).st_mtime_ns
+                except OSError:
+                    continue
+                if mtime == last:
+                    continue
+                last = mtime
+                try:
+                    agents = reload_agents()
+                    self.options.agents = agents
+                    self.log("info", f"Reloaded agents from agentcore.json ({len(agents)} agent(s))")
+                except Exception as err:  # noqa: BLE001
+                    self.log("warn", f"Failed to reload agentcore.json: {err}")
+
+        self._watcher = threading.Thread(target=watch, daemon=True)
+        self._watcher.start()
+
+    # --- HTTP -------------------------------------------------------------------------------
+
+    @property
+    def allowed_origins(self) -> list[str]:
+        return [f"http://localhost:{self.options.ui_port}", WEB_UI_LOCAL_URL]
+
+    def set_cors_headers(self, res: Response, origin: str | None = None) -> None:
+        allowed = self.allowed_origins
+        res.set_header("Access-Control-Allow-Origin", origin if origin and origin in allowed else allowed[0])
+        res.set_header("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+        res.set_header("Access-Control-Allow-Headers", "Content-Type, X-Agentcore-Local, Mcp-Session-Id")
+        res.set_header("Access-Control-Expose-Headers", "Mcp-Session-Id, x-session-id")
+        res.set_header("Vary", "Origin")
+
+    def read_body(self, req: Request) -> str:
+        return req.text()
+
+    def _handle(self, req: Request, res: Response) -> None:
+        import re
+
+        # DNS rebinding protection: only localhost / 127.0.0.1 Host headers.
+        host = re.sub(r":\d+$", "", req.header("host") or "")
+        if host not in ("localhost", "127.0.0.1"):
+            self.log("warn", f"Blocked request with unexpected Host: {req.header('host')}")
+            res.write_head(403, {"Content-Type": "text/plain"})
+            res.end("Forbidden")
+            return
+
+        origin = req.header("origin")
+        # Server-side origin validation before any side effects.
+        if origin and origin not in self.allowed_origins:
+            self.log("warn", f"Blocked cross-origin request from {origin}")
+            res.write_head(403, {"Content-Type": "text/plain"})
+            res.end("Forbidden")
+            return
+
+        if req.method == "OPTIONS":
+            self.set_cors_headers(res, origin)
+            res.write_head(204)
+            res.end()
+            return
+
+        # Custom header on POSTs forces a CORS preflight for cross-origin callers.
+        if req.method == "POST" and not req.header("x-agentcore-local"):
+            res.write_head(403, {"Content-Type": "text/plain"})
+            res.end("Forbidden: missing X-Agentcore-Local header")
+            return
+
+        try:
+            self._route(req, res, origin)
+        except Exception as err:  # noqa: BLE001 - request boundary
+            self.log("error", f"Request error: {err}")
+            if not res.headers_sent:
+                self.set_cors_headers(res, origin)
+                res.write_head(500, {"Content-Type": "text/plain"})
+                res.end("Internal Server Error")
+
+    def _route(self, req: Request, res: Response, origin: str | None) -> None:
+        from agentcore.operations.dev.web_ui import handlers as h
+
+        method, url = req.method, req.url or ""
+        if method == "GET" and url == "/api/status":
+            h.handle_status(self, res, origin)
+        elif method == "GET" and url == "/api/resources":
+            h.handle_resources(self, res, origin)
+        elif method == "GET" and url.startswith("/api/traces/"):
+            h.handle_get_trace(self, req, res, origin)
+        elif method == "GET" and url.startswith("/api/traces"):
+            h.handle_list_traces(self, req, res, origin)
+        elif method == "GET" and url.startswith("/api/cloudwatch-traces/"):
+            h.handle_get_cloud_watch_trace(self, req, res, origin)
+        elif method == "GET" and url.startswith("/api/cloudwatch-traces"):
+            h.handle_list_cloud_watch_traces(self, req, res, origin)
+        elif method == "POST" and url == "/api/start":
+            h.handle_start(self, req, res, origin)
+        elif method == "POST" and url == "/api/harness/tool-response":
+            h.handle_harness_tool_response(self, req, res, origin)
+        elif method == "POST" and (url == "/invocations" or url.startswith("/invocations?")):
+            h.handle_invocations(self, req, res, origin)
+        elif method == "POST" and (url == "/api/mcp" or url.startswith("/api/mcp?")):
+            h.handle_mcp_proxy(self, req, res, origin)
+        elif method == "GET" and url.startswith("/api/a2a/agent-card"):
+            h.handle_a2a_agent_card(self, req, res, origin)
+        elif method == "GET" and url.startswith("/api/memory"):
+            h.handle_list_memory_records(self, req, res, origin)
+        elif method == "POST" and url == "/api/memory/search":
+            h.handle_retrieve_memory_records(self, req, res, origin)
+        elif method == "GET" and self._serve_static_file(req, res):
+            pass
+        else:
+            self.set_cors_headers(res, origin)
+            res.write_head(404, {"Content-Type": "text/plain"})
+            res.end("Not Found")
+
+    def _serve_static_file(self, req: Request, res: Response) -> bool:
+        dist_dir = resolve_ui_dist_dir()
+        if not dist_dir:
+            return False
+        url_path = (req.url or "/").split("?")[0]
+        ext = os.path.splitext(url_path)[1]
+        if ext and ext in MIME_TYPES:
+            file_path = os.path.normpath(os.path.join(dist_dir, url_path.lstrip("/")))
+            if not file_path.startswith(os.path.normpath(dist_dir)):
+                return False
+            if os.path.isfile(file_path):
+                headers = {"Content-Type": MIME_TYPES[ext]}
+                if ext == ".html":
+                    headers["Content-Security-Policy"] = CSP_HEADER
+                res.write_head(200, headers)
+                with open(file_path, "rb") as f:
+                    while chunk := f.read(65536):
+                        res.write(chunk)
+                res.end()
+                return True
+        index = os.path.join(dist_dir, "index.html")
+        if os.path.exists(index):  # SPA fallback
+            res.write_head(200, {"Content-Type": "text/html", "Content-Security-Policy": CSP_HEADER})
+            with open(index, "rb") as f:
+                res.write(f.read())
+            res.end()
+            return True
+        return False

agentcore/operations/eval/__init__.py

@@ -0,0 +1,8 @@
+"""On-demand evaluation operations (port of operations/eval/index.ts)."""
+
+from agentcore.operations.eval.list_eval_runs import handle_list_eval_runs
+from agentcore.operations.eval.logs_eval import handle_logs_eval
+from agentcore.operations.eval.pause_resume import handle_pause_resume
+from agentcore.operations.eval.run_eval import discover_sessions, handle_run_eval
+
+__all__ = ["discover_sessions", "handle_list_eval_runs", "handle_logs_eval", "handle_pause_resume", "handle_run_eval"]

agentcore/operations/eval/list_eval_runs.py

@@ -0,0 +1,18 @@
+"""List saved eval runs (port of operations/eval/list-eval-runs.ts)."""
+
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.operations.eval.storage import list_eval_runs
+
+
+def handle_list_eval_runs(agent: str | None = None, limit: int | None = None) -> Ok | Err:
+    """Ok({"runs": [...]})."""
+    try:
+        runs = list_eval_runs()
+        if agent:
+            runs = [r for r in runs if r.get("agent") == agent]
+        if limit:
+            runs = runs[:limit]
+        return Ok({"runs": runs})
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))

agentcore/operations/eval/logs_eval.py

@@ -0,0 +1,119 @@
+"""Stream or search online eval logs (port of operations/eval/logs-eval.ts)."""
+
+import json
+import threading
+import time
+from typing import Any
+
+import typer
+
+from agentcore.aws import agentcore_control as control
+from agentcore.aws import cloudwatch
+from agentcore.aws._aws_errors import aws_error_name
+from agentcore.lib import ResourceNotFoundError, ValidationError
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.lib.utils.time_parser import parse_time_string
+from agentcore.operations import resolve_agent as _resolve_agent
+from agentcore.operations.jobs.shared.format import iso_from_ms, parse_int
+
+
+def format_log_line(event: dict[str, Any], as_json: bool) -> str:
+    ts = iso_from_ms(event["timestamp"])
+    if as_json:
+        return json.dumps({"timestamp": ts, "message": event["message"]}, separators=(",", ":"), ensure_ascii=False)
+    return f"{ts}  {event['message']}"
+
+
+def resolve_eval_log_groups(context: Any, target_name: str, region: str) -> list[dict[str, Any]]:
+    project = to_jsonable(context.project)
+    deployed = to_jsonable(context.deployed_state)
+    resources = ((deployed.get("targets") or {}).get(target_name) or {}).get("resources") or {}
+    results = []
+    for config in project.get("onlineEvalConfigs") or []:
+        state = (resources.get("onlineEvalConfigs") or {}).get(config["name"])
+        if not state or not state.get("onlineEvaluationConfigId"):
+            continue
+        config_id = state["onlineEvaluationConfigId"]
+        fallback = f"/aws/bedrock-agentcore/evaluations/results/{config_id}"
+        try:
+            api_config = control.get_online_evaluation_config(region=region, config_id=config_id)
+            results.append(
+                {
+                    "logGroupName": api_config.get("outputLogGroupName") or fallback,
+                    "configName": config["name"],
+                    "failureReason": api_config.get("failureReason"),
+                }
+            )
+        except Exception:  # noqa: BLE001 - fall back to the convention-based name
+            results.append({"logGroupName": fallback, "configName": config["name"]})
+    return results
+
+
+def handle_logs_eval(
+    *,
+    agent: str | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: str | None = None,
+    as_json: bool = False,
+    follow: bool | None = None,
+    abort: threading.Event | None = None,
+) -> Ok | Err:
+    context = _resolve_agent.load_deployed_project_config()
+    resolved = _resolve_agent.resolve_agent(context, agent)
+    if not resolved.success:
+        return Err(ResourceNotFoundError(resolved.error or ""))
+    target = resolved.agent
+    assert target is not None
+    log_groups = resolve_eval_log_groups(context, target.target_name, target.region)
+    if not log_groups:
+        return Err(
+            ValidationError(
+                "No deployed online eval configs found. Add one with 'agentcore add online-eval' and deploy."
+            )
+        )
+    for lg in log_groups:
+        if lg.get("failureReason"):
+            typer.echo(
+                f"Warning: Online eval config '{lg['configName']}' has a failure: {lg['failureReason']}", err=True
+            )
+
+    is_follow = follow if follow is not None else (not since and not until)
+    abort = abort or threading.Event()
+    try:
+        for lg in log_groups:
+            name = lg["logGroupName"]
+            if not is_follow:
+                now_ms = int(time.time() * 1000)
+                start = parse_time_string(since) if since else now_ms - 3_600_000
+                end = parse_time_string(until) if until else now_ms
+                try:
+                    for event in cloudwatch.search_logs(
+                        log_group_name=name,
+                        region=target.region,
+                        start_time_ms=start,
+                        end_time_ms=end,
+                        limit=parse_int(limit) if limit else None,
+                    ):
+                        typer.echo(format_log_line(event, as_json))
+                except Exception as exc:
+                    if aws_error_name(exc) == "ResourceNotFoundException":
+                        continue
+                    raise
+            else:
+                typer.echo(f"Streaming eval logs for {target.agent_name} from {name}... (Ctrl+C to stop)", err=True)
+                try:
+                    for event in cloudwatch.stream_logs(
+                        log_group_name=name, region=target.region, account_id=target.account_id, abort_signal=abort
+                    ):
+                        typer.echo(format_log_line(event, as_json))
+                except Exception as exc:
+                    if aws_error_name(exc) == "ResourceNotFoundException":
+                        typer.echo(f"Log group {name} not found yet — waiting for online eval results...", err=True)
+                        continue
+                    raise
+        return Ok(None)
+    except KeyboardInterrupt:
+        abort.set()
+        return Ok(None)

agentcore/operations/eval/pause_resume.py

@@ -0,0 +1,90 @@
+"""Pause/resume a deployed online eval config (port of operations/eval/pause-resume.ts)."""
+
+import re
+from typing import Any
+
+from agentcore.aws import agentcore_control as control
+from agentcore.lib import ResourceNotFoundError
+from agentcore.lib.errors.types import to_error
+from agentcore.lib.result import Err, Ok
+from agentcore.lib.schemas.io.config_io import to_jsonable
+from agentcore.operations import resolve_agent as _resolve_agent
+
+Resolution = dict[str, Any]
+
+
+def _resolve_by_name(config_name: str) -> Resolution:
+    context = _resolve_agent.load_deployed_project_config()
+    deployed = to_jsonable(context.deployed_state)
+    targets = deployed.get("targets") or {}
+    if not targets:
+        return {"success": False, "error": "No deployed targets found. Run `agentcore deploy` first."}
+    target_name = next(iter(targets))
+    resources = (targets[target_name] or {}).get("resources") or {}
+    deployed_config = (resources.get("onlineEvalConfigs") or {}).get(config_name)
+    if not deployed_config:
+        return {
+            "success": False,
+            "error": f'Online eval config "{config_name}" not found in deployed state. Has it been deployed?',
+        }
+    target_config = next((t for t in context.aws_targets if t.name == target_name), None)
+    if target_config is None:
+        return {"success": False, "error": f'Target config "{target_name}" not found in aws-targets.'}
+    return {"success": True, "configId": deployed_config["onlineEvaluationConfigId"], "region": target_config.region}
+
+
+def parse_online_eval_config_arn(arn: str, region_override: str | None = None) -> Resolution:
+    parts = arn.split(":")
+    if len(parts) < 6 or not arn.startswith("arn:"):
+        return {"success": False, "error": f"Invalid online eval config ARN: {arn}"}
+    region = region_override if region_override is not None else parts[3]
+    if not region:
+        return {"success": False, "error": "Could not determine region from ARN. Use --region to specify."}
+    match = re.search(r"online-evaluation-config/(.+)$", ":".join(parts[5:]))
+    if not match:
+        return {"success": False, "error": f"Could not extract config ID from ARN: {arn}"}
+    return {"success": True, "configId": match.group(1), "region": region}
+
+
+def _resolve_config(name: str, arn: str | None, region: str | None) -> Resolution:
+    if arn and name:
+        by_arn = parse_online_eval_config_arn(arn, region)
+        if not by_arn["success"]:
+            return by_arn
+        by_name = _resolve_by_name(name)
+        if not by_name["success"]:
+            return by_name
+        if by_name["configId"] != by_arn["configId"]:
+            return {
+                "success": False,
+                "error": f'--arn and config name "{name}" refer to different configs '
+                f'(name resolves to "{by_name["configId"]}", ARN resolves to "{by_arn["configId"]}"). '
+                "Pass only one, or pass matching values.",
+            }
+        if by_name["region"] != by_arn["region"]:
+            return {
+                "success": False,
+                "error": f'--arn and config name "{name}" resolve to different regions '
+                f'(name resolves to "{by_name["region"]}", ARN resolves to "{by_arn["region"]}"). '
+                "Pass only one, or use --region to override.",
+            }
+        return by_arn
+    if arn:
+        return parse_online_eval_config_arn(arn, region)
+    return _resolve_by_name(name)
+
+
+def handle_pause_resume(*, name: str, action: str, arn: str | None = None, region: str | None = None) -> Ok | Err:
+    """Ok({"configId", "executionStatus"})."""
+    resolution = _resolve_config(name, arn, region)
+    if not resolution["success"]:
+        return Err(ResourceNotFoundError(resolution["error"]))
+    try:
+        result = control.update_online_eval_execution_status(
+            region=resolution["region"],
+            online_evaluation_config_id=resolution["configId"],
+            execution_status="DISABLED" if action == "pause" else "ENABLED",
+        )
+        return Ok({"configId": result["configId"], "executionStatus": result["executionStatus"]})
+    except Exception as exc:  # noqa: BLE001
+        return Err(to_error(exc))