agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/_http.py

@@ -0,0 +1,79 @@
+"""Minimal fetch()-like HTTP client for talking to local agent processes (localhost only).
+
+Connection failures are raised as :class:`FetchFailedError` (message ``fetch failed``), matching
+how upstream classifies Node fetch errors for retry decisions.
+"""
+
+import http.client
+import json
+from collections.abc import Iterator, Mapping
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlsplit
+
+from agentcore.operations.dev.utils import FetchFailedError
+
+
+@dataclass
+class LocalResponse:
+    status: int
+    headers: http.client.HTTPMessage
+    _resp: http.client.HTTPResponse
+    _conn: http.client.HTTPConnection
+
+    @property
+    def ok(self) -> bool:
+        return 200 <= self.status < 300
+
+    def header(self, name: str) -> str | None:
+        return self.headers.get(name)
+
+    def iter_chunks(self, size: int = 8192) -> Iterator[bytes]:
+        try:
+            while True:
+                chunk = self._resp.read1(size)
+                if not chunk:
+                    break
+                yield chunk
+        finally:
+            self.close()
+
+    def read(self) -> bytes:
+        try:
+            return self._resp.read()
+        finally:
+            self.close()
+
+    def text(self) -> str:
+        return self.read().decode("utf-8", errors="replace")
+
+    def json(self) -> Any:
+        return json.loads(self.text())
+
+    def close(self) -> None:
+        try:
+            self._resp.close()
+        finally:
+            self._conn.close()
+
+
+def fetch(
+    url: str,
+    method: str = "GET",
+    headers: Mapping[str, str] | None = None,
+    body: str | bytes | None = None,
+    timeout: float | None = None,
+) -> LocalResponse:
+    parts = urlsplit(url)
+    conn = http.client.HTTPConnection(parts.hostname or "localhost", parts.port or 80, timeout=timeout)
+    path = parts.path or "/"
+    if parts.query:
+        path += f"?{parts.query}"
+    data = body.encode("utf-8") if isinstance(body, str) else body
+    try:
+        conn.request(method, path, body=data, headers=dict(headers or {}))
+        resp = conn.getresponse()
+    except (ConnectionError, OSError) as exc:
+        conn.close()
+        raise FetchFailedError(exc) from exc
+    return LocalResponse(status=resp.status, headers=resp.headers, _resp=resp, _conn=conn)

agentcore/operations/dev/_server.py

@@ -0,0 +1,165 @@
+"""stdlib HTTP server plumbing with a Node ``ServerResponse``-like API.
+
+Handlers are ported from Node's ``http`` module and written against :class:`Response`
+(``set_header`` / ``write_head`` / ``write`` / ``end`` / ``headers_sent``). Responses without a
+``Content-Length`` use chunked transfer encoding (as Node does), so SSE streams flush per write and
+HTTP/1.1 keep-alive still works.
+"""
+
+import json
+import threading
+from collections.abc import Callable
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from typing import Any
+
+
+def js_dumps(value: Any) -> str:
+    """``JSON.stringify(value)``: compact, non-ASCII kept, ``None`` dict values dropped (undefined)."""
+
+    def clean(v: Any) -> Any:
+        if isinstance(v, dict):
+            return {k: clean(x) for k, x in v.items() if x is not None}
+        if isinstance(v, (list, tuple)):
+            return [clean(x) for x in v]
+        return v
+
+    return json.dumps(clean(value), ensure_ascii=False, separators=(",", ":"))
+
+
+class Request:
+    def __init__(self, handler: BaseHTTPRequestHandler):
+        self._handler = handler
+        self.method = handler.command
+        self.url = handler.path
+        self.headers = handler.headers
+        self._body: bytes | None = None
+
+    def header(self, name: str) -> str | None:
+        return self.headers.get(name)
+
+    def read_body(self) -> bytes:
+        if self._body is None:
+            length = int(self.headers.get("Content-Length") or 0)
+            if length:
+                self._body = self._handler.rfile.read(length)
+            elif "chunked" in (self.headers.get("Transfer-Encoding") or "").lower():
+                self._body = self._read_chunked()
+            else:
+                self._body = b""
+        return self._body
+
+    def _read_chunked(self) -> bytes:
+        rfile = self._handler.rfile
+        out = bytearray()
+        while True:
+            size_line = rfile.readline().strip().split(b";")[0]
+            size = int(size_line or b"0", 16)
+            if size == 0:
+                while rfile.readline() not in (b"\r\n", b"\n", b""):
+                    pass
+                return bytes(out)
+            out += rfile.read(size)
+            rfile.readline()
+
+    def text(self) -> str:
+        return self.read_body().decode("utf-8", errors="replace")
+
+
+class Response:
+    def __init__(self, handler: BaseHTTPRequestHandler):
+        self._handler = handler
+        self._headers: dict[str, str] = {}
+        self.headers_sent = False
+        self.finished = False
+        self._chunked = False
+        self._lock = threading.Lock()
+
+    def set_header(self, name: str, value: str) -> None:
+        self._headers[name] = value
+
+    def write_head(self, status: int, headers: dict[str, str] | None = None) -> None:
+        if self.headers_sent:
+            return
+        merged = {**self._headers, **(headers or {})}
+        h = self._handler
+        h.send_response_only(status)
+        h.send_header("Date", h.date_time_string())
+        for name, value in merged.items():
+            h.send_header(name, value)
+        if not any(k.lower() == "content-length" for k in merged):
+            if h.request_version == "HTTP/1.1" and h.command != "HEAD" and status not in (204, 304):
+                self._chunked = True
+                h.send_header("Transfer-Encoding", "chunked")
+            elif status not in (204, 304):
+                h.close_connection = True
+        h.end_headers()
+        self.headers_sent = True
+
+    def write(self, data: str | bytes) -> None:
+        if self.finished:
+            return
+        if not self.headers_sent:
+            self.write_head(200)
+        payload = data.encode("utf-8") if isinstance(data, str) else data
+        if not payload:
+            return
+        with self._lock:
+            try:
+                if self._chunked:
+                    self._handler.wfile.write(f"{len(payload):X}\r\n".encode() + payload + b"\r\n")
+                else:
+                    self._handler.wfile.write(payload)
+                self._handler.wfile.flush()
+            except OSError:
+                self._handler.close_connection = True
+
+    def end(self, data: str | bytes | None = None) -> None:
+        if self.finished:
+            return
+        if data:
+            self.write(data)
+        if not self.headers_sent:
+            self.write_head(200)
+        with self._lock:
+            try:
+                if self._chunked:
+                    self._handler.wfile.write(b"0\r\n\r\n")
+                self._handler.wfile.flush()
+            except OSError:
+                self._handler.close_connection = True
+        self.finished = True
+
+
+RouteFn = Callable[[Request, Response], None]
+
+
+def make_server(host: str, port: int, route: RouteFn) -> ThreadingHTTPServer:
+    """Threaded server where every request (any method) is dispatched to ``route``."""
+
+    class Handler(BaseHTTPRequestHandler):
+        protocol_version = "HTTP/1.1"
+
+        def log_message(self, format: str, *args: Any) -> None:
+            pass
+
+        def _dispatch(self) -> None:
+            req, res = Request(self), Response(self)
+            try:
+                route(req, res)
+            finally:
+                if not res.finished:
+                    res.end()
+                # Drain an unread request body so the next keep-alive request parses cleanly.
+                if req._body is None and int(self.headers.get("Content-Length") or 0):
+                    try:
+                        req.read_body()
+                    except OSError:
+                        self.close_connection = True
+
+        do_GET = do_POST = do_PUT = do_DELETE = do_PATCH = do_OPTIONS = do_HEAD = _dispatch
+
+    class Server(ThreadingHTTPServer):
+        daemon_threads = True
+        allow_reuse_address = True
+
+    return Server((host, port), Handler)

agentcore/operations/dev/codezip_dev_server.py

@@ -0,0 +1,151 @@
+"""Port of operations/dev/codezip-dev-server.ts: run uvicorn / python / `npx tsx watch` locally."""
+
+import os
+import subprocess
+from collections.abc import Callable
+
+from agentcore.lib.utils.platform import get_shell_args, get_shell_command, get_venv_executable, is_windows
+from agentcore.lib.utils.subprocess import run_subprocess_capture
+from agentcore.operations.dev.constants import A2A_PORT_ENV
+from agentcore.operations.dev.dev_server import DevServer, LogLevel, SpawnConfig
+from agentcore.operations.dev.utils import convert_entrypoint_to_module
+
+OnLog = Callable[[LogLevel, str], None]
+
+
+def _run_uv(args: list[str], cwd: str) -> subprocess.CompletedProcess[bytes] | None:
+    try:
+        return subprocess.run(["uv", *args], cwd=cwd, stdin=subprocess.DEVNULL, capture_output=True)
+    except OSError:
+        return None
+
+
+def _stderr(result: subprocess.CompletedProcess[bytes] | None) -> str:
+    text = result.stderr.decode("utf-8", errors="replace") if result is not None and result.stderr else ""
+    return text or "unknown error"
+
+
+def ensure_python_venv(cwd: str, on_log: OnLog, protocol: str = "HTTP") -> bool:
+    """Create .venv and `uv sync` unless the venv already has uvicorn (HTTP) or python (others)."""
+    venv_path = os.path.join(cwd, ".venv")
+    probe = get_venv_executable(venv_path, "uvicorn" if protocol == "HTTP" else "python")
+    if os.path.exists(probe):
+        return True
+
+    on_log("system", "Setting up Python environment...")
+
+    if not os.path.exists(venv_path):
+        on_log("info", "Creating virtual environment...")
+        result = _run_uv(["venv"], cwd)
+        if result is None or result.returncode != 0:
+            on_log("error", f"Failed to create venv: {_stderr(result)}")
+            return False
+
+    on_log("info", "Installing dependencies...")
+    sync = _run_uv(["sync"], cwd)
+    if sync is None or sync.returncode != 0:
+        if protocol == "HTTP":
+            on_log("warn", "uv sync failed, trying direct uvicorn install...")
+            pip = _run_uv(["pip", "install", "uvicorn"], cwd)
+            if pip is None or pip.returncode != 0:
+                on_log("error", f"Failed to install dependencies: {_stderr(pip)}")
+                return False
+        else:
+            on_log("error", f"Failed to install dependencies: {_stderr(sync)}")
+            return False
+
+    on_log("system", "Python environment ready")
+    return True
+
+
+def ensure_node_deps(cwd: str, on_log: OnLog) -> bool:
+    """Install Node deps (pnpm/yarn by lockfile, else npm) when node_modules is missing."""
+    if os.path.exists(os.path.join(cwd, "node_modules")):
+        return True
+    cmd = "npm"
+    if os.path.exists(os.path.join(cwd, "pnpm-lock.yaml")):
+        cmd = "pnpm"
+    elif os.path.exists(os.path.join(cwd, "yarn.lock")):
+        cmd = "yarn"
+    on_log("system", "Installing Node dependencies...")
+    result = run_subprocess_capture(cmd, ["install"], cwd=cwd)
+    if result.code != 0:
+        detail = result.stderr or result.stdout or f"{cmd} exited with code {result.code}"
+        on_log("error", f"Failed to install Node dependencies: {detail}")
+        return False
+    on_log("system", "Node dependencies ready")
+    return True
+
+
+def find_otel_sitecustomize_dir(venv_path: str) -> str | None:
+    """Directory holding OpenTelemetry's auto-instrumentation sitecustomize.py, if installed."""
+    try:
+        result = subprocess.run(
+            [
+                get_venv_executable(venv_path, "python"),
+                "-c",
+                "import opentelemetry.instrumentation.auto_instrumentation as m; import os; "
+                "print(os.path.dirname(m.__file__))",
+            ],
+            cwd=venv_path,
+            stdin=subprocess.DEVNULL,
+            capture_output=True,
+        )
+    except OSError:
+        return None
+    if result.returncode == 0:
+        directory = result.stdout.decode("utf-8", errors="replace").strip()
+        if directory and os.path.exists(os.path.join(directory, "sitecustomize.py")):
+            return directory
+    return None
+
+
+class CodeZipDevServer(DevServer):
+    """Runs uvicorn --reload (Python HTTP), `python main.py` (other Python), or `npx tsx watch`."""
+
+    def prepare(self) -> bool:
+        if self.config.is_python:
+            return ensure_python_venv(self.config.directory, self.options.callbacks.on_log, self.config.protocol)
+        return ensure_node_deps(self.config.directory, self.options.callbacks.on_log)
+
+    def get_spawn_config(self) -> SpawnConfig:
+        module, directory, protocol = self.config.module, self.config.directory, self.config.protocol
+        port = self.options.port
+        env_vars = self.options.env_vars or {}
+        env = {**os.environ, **env_vars, "PORT": str(port), "LOCAL_DEV": "1"}
+
+        # FastMCP currently ignores FASTMCP_PORT (always binds 8000); set it for forward compatibility.
+        if protocol == "MCP":
+            env["FASTMCP_PORT"] = str(port)
+        if protocol == "A2A":
+            env["AGENTCORE_RUNTIME_URL"] = f"http://localhost:{port}/"
+            env[A2A_PORT_ENV] = str(port)
+
+        if not self.config.is_python:
+            entry_file = module.split(":")[0] or module
+            if is_windows:
+                return SpawnConfig(
+                    cmd=get_shell_command(), args=get_shell_args(f"npx tsx watch {entry_file}"), cwd=directory, env=env
+                )
+            return SpawnConfig(cmd="npx", args=["tsx", "watch", entry_file], cwd=directory, env=env)
+
+        venv_dir = os.path.join(directory, ".venv")
+        # Prepend OTEL's sitecustomize dir to PYTHONPATH so both the uvicorn reloader and every worker
+        # it spawns are auto-instrumented (opentelemetry-instrument would only wrap the reloader).
+        otel_dir = find_otel_sitecustomize_dir(venv_dir)
+        if env_vars.get("OTEL_EXPORTER_OTLP_ENDPOINT") and otel_dir:
+            existing = env.get("PYTHONPATH", "")
+            env["PYTHONPATH"] = f"{otel_dir}{os.pathsep}{existing}" if existing else otel_dir
+
+        if protocol != "HTTP":
+            python = get_venv_executable(venv_dir, "python")
+            entry_file = module.split(":")[0] or module
+            return SpawnConfig(cmd=python, args=[entry_file], cwd=directory, env=env)
+
+        uvicorn = get_venv_executable(venv_dir, "uvicorn")
+        return SpawnConfig(
+            cmd=uvicorn,
+            args=[convert_entrypoint_to_module(module), "--reload", "--host", "127.0.0.1", "--port", str(port)],
+            cwd=directory,
+            env=env,
+        )

agentcore/operations/dev/config.py

@@ -0,0 +1,128 @@
+"""Port of operations/dev/config.ts: derive the dev server config for a runtime."""
+
+import os
+from dataclasses import dataclass
+from typing import Any
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+from agentcore.lib.schemas.io.path_resolver import find_config_root
+from agentcore.operations.dev.constants import A2A_DEFAULT_PORT, MCP_DEFAULT_PORT
+
+
+@dataclass
+class DevConfig:
+    agent_name: str
+    module: str
+    directory: str
+    has_config: bool
+    is_python: bool
+    build_type: str
+    protocol: str
+    dockerfile: str | None = None
+    build_context_path: str | None = None
+    """Resolved absolute path to use as the Docker build context. Defaults to ``directory``."""
+    custom_docker_build_args: dict[str, str] | None = None
+
+
+def _runtimes(project: Any) -> list[Any]:
+    return list(getattr(project, "runtimes", None) or [])
+
+
+def _is_python_agent(agent: Any) -> bool:
+    entrypoint = agent.entrypoint or ""
+    return entrypoint.endswith(".py") or ".py:" in entrypoint
+
+
+def _dev_support_reason(agent: Any) -> str | None:
+    if not getattr(agent, "entrypoint", None):
+        return f'Agent "{agent.name}" is missing entrypoint.'
+    return None
+
+
+def _resolve_code_directory(code_location: str, config_root: str) -> str:
+    clean = code_location.removesuffix("/")
+    if os.path.isabs(clean):
+        return clean
+    return os.path.normpath(os.path.join(os.path.dirname(config_root), clean))
+
+
+def get_dev_supported_agents(project: Any | None) -> list[Any]:
+    if project is None:
+        return []
+    return [a for a in _runtimes(project) if _dev_support_reason(a) is None]
+
+
+def requires_exact_dev_port(protocol: str) -> bool:
+    """A2A derives its port from config and FastMCP ignores overrides: neither can move."""
+    return protocol in ("A2A", "MCP")
+
+
+def get_agent_port(project: Any | None, agent_name: str, base_port: int, explicit: bool = False) -> int:
+    """Explicit ports are used literally; default ports are offset by the runtime's index."""
+    if explicit or project is None:
+        return base_port
+    names = [a.name for a in _runtimes(project)]
+    return base_port + names.index(agent_name) if agent_name in names else base_port
+
+
+def get_dev_port(project: Any | None, agent_name: str, protocol: str, base_port: int, explicit: bool = False) -> int:
+    if protocol == "MCP":
+        return MCP_DEFAULT_PORT
+    if explicit:
+        return base_port
+    protocol_base = A2A_DEFAULT_PORT if protocol == "A2A" else base_port
+    return get_agent_port(project, agent_name, protocol_base)
+
+
+def get_dev_config(
+    working_dir: str, project: Any | None, config_root: str | None = None, agent_name: str | None = None
+) -> DevConfig | None:
+    if project is None:
+        raise ValueError("No project configuration found")
+
+    if agent_name:
+        target = next((a for a in _runtimes(project) if a.name == agent_name), None)
+        if target is None:
+            raise ValueError(f'Agent "{agent_name}" not found in project.')
+    else:
+        supported = get_dev_supported_agents(project)
+        target = supported[0] if supported else None
+
+    if target is None:
+        return None
+
+    reason = _dev_support_reason(target)
+    if reason is not None:
+        raise ValueError(reason)
+
+    code_location = getattr(target, "code_location", None)
+    directory = _resolve_code_directory(code_location, config_root) if config_root and code_location else working_dir
+    build_context = getattr(target, "build_context_path", None)
+    return DevConfig(
+        agent_name=target.name,
+        module=target.entrypoint,
+        directory=directory,
+        has_config=True,
+        is_python=_is_python_agent(target),
+        build_type=target.build,
+        protocol=getattr(target, "protocol", None) or "HTTP",
+        dockerfile=getattr(target, "dockerfile", None),
+        build_context_path=_resolve_code_directory(build_context, config_root)
+        if config_root and build_context
+        else None,
+        custom_docker_build_args=getattr(target, "custom_docker_build_args", None),
+    )
+
+
+def load_project_config(working_dir: str) -> Any | None:
+    """Read agentcore.json from the project containing ``working_dir``; None if missing/invalid."""
+    config_root = find_config_root(working_dir)
+    if not config_root:
+        return None
+    config_io = ConfigIO(base_dir=config_root)
+    if not config_io.config_exists("project"):
+        return None
+    try:
+        return config_io.read_project_spec()
+    except Exception:  # noqa: BLE001 - invalid config is treated as "no project", as upstream
+        return None

agentcore/operations/dev/constants.py

@@ -0,0 +1,9 @@
+"""Port of operations/dev/constants.ts."""
+
+MCP_DEFAULT_PORT = 8000
+A2A_DEFAULT_PORT = 9000
+
+# Protocol-scoped port override read by the SDK's `serve_a2a()`. The generic `PORT` is not used
+# for A2A: shared images set it to another protocol's port (8080 for HTTP, 8000 for MCP), which
+# would bind the A2A server off-contract.
+A2A_PORT_ENV = "A2A_PORT"