agentcore-cli 0.31.1__py3-none-any.whl

agentcore/operations/dev/container_dev_server.py

@@ -0,0 +1,237 @@
+"""Port of operations/dev/container-dev-server.ts: build and run the agent's Docker image locally."""
+
+import os
+import re
+import subprocess
+import threading
+from collections.abc import Callable
+
+from agentcore.lib.constants import CONTAINER_INTERNAL_PORT, DOCKERFILE_NAME, get_dockerfile_path
+from agentcore.lib.packaging.build_args import get_custom_build_args, get_uv_build_args
+from agentcore.lib.packaging.build_context_dockerignore import ensure_build_context_dockerignore
+from agentcore.operations.dev.constants import A2A_DEFAULT_PORT, A2A_PORT_ENV, MCP_DEFAULT_PORT
+from agentcore.operations.dev.container_runtime import detect_container_runtime
+from agentcore.operations.dev.dev_server import DevServer, LogLevel, SpawnConfig
+from agentcore.operations.dev.utils import wait_for_server_ready
+
+
+class ContainerDevServer(DevServer):
+    runtime_binary = ""
+
+    @property
+    def image_name(self) -> str:
+        """Docker image names must be lowercase."""
+        return f"agentcore-dev-{self.config.agent_name}".lower()
+
+    @property
+    def container_name(self) -> str:
+        return self.image_name
+
+    def start(self):  # type: ignore[no-untyped-def]
+        """Spawn `docker run`, then wait (up to 60s) for the mapped port to accept connections."""
+        child = super().start()
+        if child is not None:
+            on_log = self.options.callbacks.on_log
+            on_log("system", f"Container {self.container_name} started, waiting for server to be ready...")
+            if wait_for_server_ready(self.options.port):
+                # Readiness marker the terminal dev loop looks for.
+                on_log("info", "Application startup complete")
+            else:
+                on_log("error", "Container server did not become ready within 60 seconds.")
+        return child
+
+    def kill(self) -> None:
+        """Stop the container (fire-and-forget) so its port proxy is cleaned up, then kill the client."""
+        if self.runtime_binary:
+            try:
+                subprocess.Popen(
+                    [self.runtime_binary, "stop", self.container_name],
+                    stdin=subprocess.DEVNULL,
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                )
+            except OSError:
+                pass
+        super().kill()
+
+    def prepare(self) -> bool:
+        on_log = self.options.callbacks.on_log
+
+        runtime = detect_container_runtime()
+        if runtime is None:
+            on_log("error", "No container runtime found. Install Docker, Podman, or Finch.")
+            return False
+        self.runtime_binary = runtime.binary
+
+        build_context = self.config.build_context_path or self.config.directory
+        dockerfile_name = self.config.dockerfile or DOCKERFILE_NAME
+        dockerfile_path = get_dockerfile_path(build_context, self.config.dockerfile)
+        if not os.path.exists(dockerfile_path):
+            on_log("error", f"{dockerfile_name} not found at {dockerfile_path}. Container agents require a Dockerfile.")
+            return False
+
+        if self.config.build_context_path:
+            created = ensure_build_context_dockerignore(build_context)
+            if created:
+                on_log(
+                    "system",
+                    f"Created {created} with default secret exclusions (buildContextPath is set); review and commit it.",
+                )
+
+        # Remove any stale container from a previous run (prevents "proxy already running" errors).
+        try:
+            subprocess.run(
+                [self.runtime_binary, "rm", "-f", self.container_name],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.DEVNULL,
+                stderr=subprocess.DEVNULL,
+            )
+        except OSError:
+            pass
+
+        on_log("system", f"Building container image: {self.image_name}...")
+        build_arg_flags = get_custom_build_args(self.config.custom_docker_build_args)
+        exit_code = self._stream_build(
+            ["-t", self.image_name, "-f", dockerfile_path, *get_uv_build_args(), *build_arg_flags, build_context],
+            on_log,
+        )
+        if exit_code != 0:
+            on_log("error", f"Container build failed (exit code {exit_code})")
+            return False
+        on_log("system", "Container image built successfully.")
+        return True
+
+    def _stream_build(self, args: list[str], on_log: Callable[[LogLevel, str], None]) -> int | None:
+        try:
+            proc = subprocess.Popen(
+                [self.runtime_binary, "build", *args],
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+            )
+        except OSError as exc:
+            on_log("error", f"Build process error: {exc}")
+            return 1
+
+        def pump(stream) -> None:  # type: ignore[no-untyped-def]
+            for raw in iter(stream.readline, b""):
+                line = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+                if line.strip():
+                    on_log("system", line)
+            stream.close()
+
+        threads = [threading.Thread(target=pump, args=(s,), daemon=True) for s in (proc.stdout, proc.stderr)]
+        for t in threads:
+            t.start()
+        returncode = proc.wait()
+        for t in threads:
+            t.join()
+        return None if returncode < 0 else returncode
+
+    def _resolve_host_credentials(self) -> dict[str, str] | None:
+        """Resolve AWS credentials on the host via `aws configure export-credentials`.
+
+        Container images run as a non-root user that cannot read the mounted ~/.aws files and
+        lack credential_process helpers, so short-lived host credentials are injected instead.
+        """
+        profile = os.environ.get("AWS_PROFILE", "default")
+        try:
+            result = subprocess.run(
+                ["aws", "configure", "export-credentials", "--format", "env", "--profile", profile],
+                stdin=subprocess.DEVNULL,
+                capture_output=True,
+                text=True,
+                timeout=10,
+                env=dict(os.environ),
+            )
+        except (OSError, subprocess.TimeoutExpired):
+            return None
+        if result.returncode != 0 or not result.stdout:
+            return None
+        creds: dict[str, str] = {}
+        for line in result.stdout.split("\n"):
+            match = re.match(r"^export\s+(AWS_\w+)=(.+)$", line)
+            if match and match.group(1) and match.group(2):
+                creds[match.group(1)] = match.group(2)
+        return creds if creds.get("AWS_ACCESS_KEY_ID") else None
+
+    def get_spawn_config(self) -> SpawnConfig:
+        port = self.options.port
+        env_vars = self.options.env_vars or {}
+        protocol = self.config.protocol
+        internal_port = (
+            A2A_DEFAULT_PORT
+            if protocol == "A2A"
+            else MCP_DEFAULT_PORT
+            if protocol == "MCP"
+            else CONTAINER_INTERNAL_PORT
+        )
+
+        has_explicit_creds = bool(os.environ.get("AWS_ACCESS_KEY_ID"))
+        if not has_explicit_creds:
+            resolved = self._resolve_host_credentials()
+            if resolved:
+                os.environ.update(resolved)
+                has_explicit_creds = True
+
+        aws_env_keys = [
+            "AWS_ACCESS_KEY_ID",
+            "AWS_SECRET_ACCESS_KEY",
+            "AWS_SESSION_TOKEN",
+            "AWS_REGION",
+            "AWS_DEFAULT_REGION",
+            *([] if has_explicit_creds else ["AWS_PROFILE"]),
+        ]
+        aws_env = {k: os.environ[k] for k in aws_env_keys if os.environ.get(k)}
+
+        aws_dir = os.path.join(os.path.expanduser("~"), ".aws")
+        aws_container_path = "/aws-config"
+        mount = not has_explicit_creds and os.path.exists(aws_dir)
+        aws_mount_args = ["-v", f"{aws_dir}:{aws_container_path}:ro"] if mount else []
+        aws_config_env = (
+            {
+                "AWS_CONFIG_FILE": f"{aws_container_path}/config",
+                "AWS_SHARED_CREDENTIALS_FILE": f"{aws_container_path}/credentials",
+            }
+            if mount
+            else {}
+        )
+
+        # Inside the container 127.0.0.1 is the container itself: point OTEL at the host collector.
+        container_env = dict(env_vars)
+        if container_env.get("OTEL_EXPORTER_OTLP_ENDPOINT"):
+            container_env["OTEL_EXPORTER_OTLP_ENDPOINT"] = (
+                container_env["OTEL_EXPORTER_OTLP_ENDPOINT"]
+                .replace("127.0.0.1", "host.docker.internal", 1)
+                .replace("localhost", "host.docker.internal", 1)
+            )
+
+        merged = {
+            **aws_env,
+            **aws_config_env,
+            **container_env,
+            "LOCAL_DEV": "1",
+            "PORT": str(internal_port),
+            **(
+                {"AGENTCORE_RUNTIME_URL": f"http://localhost:{port}/", A2A_PORT_ENV: str(internal_port)}
+                if protocol == "A2A"
+                else {}
+            ),
+        }
+        env_args = [part for k, v in merged.items() for part in ("-e", f"{k}={v}")]
+
+        return SpawnConfig(
+            cmd=self.runtime_binary,
+            args=[
+                "run",
+                "--rm",
+                "--name",
+                self.container_name,
+                *aws_mount_args,
+                "-p",
+                f"{port}:{internal_port}",
+                *env_args,
+                self.image_name,
+            ],
+            env=dict(os.environ),
+        )

agentcore/operations/dev/container_runtime.py

@@ -0,0 +1,37 @@
+"""Port of detectContainerRuntime (src/cli/external-requirements/detect.ts) used by dev/exec.
+
+Kept local to dev because the shared `lib.packaging.container.detect_container_runtime` skips the
+``build --help`` shim check and returns only a name.
+"""
+
+import re
+from dataclasses import dataclass
+
+from agentcore.lib.constants import CONTAINER_RUNTIMES
+from agentcore.lib.utils.platform import is_windows
+from agentcore.lib.utils.subprocess import check_subprocess, run_subprocess_capture
+
+
+@dataclass(frozen=True)
+class ContainerRuntimeInfo:
+    runtime: str
+    binary: str
+    version: str
+
+
+def detect_container_runtime() -> ContainerRuntimeInfo | None:
+    for runtime in CONTAINER_RUNTIMES:
+        exists = check_subprocess("where" if is_windows else "which", [runtime])
+        if not exists:
+            continue
+        result = run_subprocess_capture(runtime, ["--version"])
+        if result.code != 0:
+            continue
+        build_check = run_subprocess_capture(runtime, ["build", "--help"])
+        if build_check.code != 0:
+            continue
+        if build_check.stderr and re.search(r"unknown command|not found", build_check.stderr, re.IGNORECASE):
+            continue
+        version = (result.stdout.strip().split("\n") or ["unknown"])[0] or "unknown"
+        return ContainerRuntimeInfo(runtime=runtime, binary=runtime, version=version)
+    return None

agentcore/operations/dev/dev_server.py

@@ -0,0 +1,244 @@
+"""Port of operations/dev/dev-server.ts: spawn and supervise the local agent process."""
+
+import atexit
+import os
+import signal
+import subprocess
+import threading
+from abc import ABC, abstractmethod
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+from agentcore.lib.utils.platform import is_windows
+from agentcore.operations.dev.config import DevConfig
+
+LogLevel = Literal["info", "warn", "error", "system"]
+
+# Keep the last 20 stderr lines so we can surface them if the process crashes.
+STDERR_BUFFER_SIZE = 20
+
+# Paths that indicate internal framework frames (not user code).
+INTERNAL_FRAME_PATTERNS = (
+    "/site-packages/",
+    "<frozen ",
+    "/multiprocessing/",
+    "/asyncio/",
+    "/concurrent/",
+    "/importlib/",
+)
+
+
+def _is_internal_frame(line: str) -> bool:
+    return any(p in line for p in INTERNAL_FRAME_PATTERNS)
+
+
+@dataclass
+class DevServerCallbacks:
+    on_log: Callable[[LogLevel, str], None]
+    on_exit: Callable[[int | None], None]
+
+
+@dataclass
+class DevServerOptions:
+    port: int
+    callbacks: DevServerCallbacks
+    env_vars: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass
+class SpawnConfig:
+    cmd: str
+    args: list[str]
+    env: dict[str, str]
+    cwd: str | None = None
+
+
+class DevServer(ABC):
+    """Base class: ``prepare()`` does mode-specific setup, ``get_spawn_config()`` the command line."""
+
+    def __init__(self, config: DevConfig, options: DevServerOptions):
+        self.config = config
+        self.options = options
+        self.child: subprocess.Popen[bytes] | None = None
+        self._killed = False
+        self._recent_stderr: list[str] = []
+        self._in_traceback = False
+        self._traceback_buffer: list[str] = []
+        self._exit_cleanup: Callable[[], None] | None = None
+        self._lock = threading.Lock()
+
+    # --- lifecycle ------------------------------------------------------------------------
+
+    def start(self) -> subprocess.Popen[bytes] | None:
+        """Prepare, then spawn the process. Returns None when preparation (or the spawn) failed."""
+        if not self.prepare():
+            self.options.callbacks.on_exit(1)
+            return None
+
+        spawn = self.get_spawn_config()
+        try:
+            self.child = subprocess.Popen(
+                [spawn.cmd, *spawn.args],
+                cwd=spawn.cwd,
+                env=spawn.env,
+                stdin=subprocess.DEVNULL,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                start_new_session=not is_windows,  # detached: own process group, like upstream
+            )
+        except OSError as exc:
+            self.options.callbacks.on_log("error", f"Failed to start: {exc}")
+            self.options.callbacks.on_exit(1)
+            return None
+
+        self._attach_handlers()
+        self._register_exit_cleanup()
+        return self.child
+
+    def _register_exit_cleanup(self) -> None:
+        """Reap the detached child's process group if this process exits without kill()."""
+        pid = self.child.pid if self.child else None
+        if is_windows or not pid:
+            return
+
+        def reap() -> None:
+            try:
+                os.killpg(pid, signal.SIGKILL)
+            except OSError:
+                pass  # group already gone
+
+        self._exit_cleanup = reap
+        atexit.register(reap)
+
+    def _clear_exit_cleanup(self) -> None:
+        if self._exit_cleanup is not None:
+            atexit.unregister(self._exit_cleanup)
+            self._exit_cleanup = None
+
+    def kill(self) -> None:
+        """SIGTERM the process tree, then SIGKILL after 2 seconds if it is still alive."""
+        if self.child is None or self._killed or self.child.poll() is not None:
+            return
+        self._killed = True
+        self._signal_process_tree(signal.SIGTERM)
+
+        def force() -> None:
+            if self.child is not None and self.child.poll() is None:
+                self._signal_process_tree(signal.SIGKILL if not is_windows else signal.SIGTERM)
+
+        timer = threading.Timer(2.0, force)
+        timer.daemon = True
+        timer.start()
+
+    def _signal_process_tree(self, sig: int) -> None:
+        child = self.child
+        if child is None:
+            return
+        try:
+            if is_windows:
+                subprocess.run(
+                    ["taskkill", "/pid", str(child.pid), "/T", "/F"],
+                    stdout=subprocess.DEVNULL,
+                    stderr=subprocess.DEVNULL,
+                    check=True,
+                )
+            else:
+                os.killpg(child.pid, sig)
+        except (OSError, subprocess.CalledProcessError):
+            try:
+                child.send_signal(sig)
+            except OSError:
+                pass
+
+    @abstractmethod
+    def prepare(self) -> bool:
+        """Mode-specific setup (venv, image build). Returns False to abort."""
+
+    @abstractmethod
+    def get_spawn_config(self) -> SpawnConfig:
+        """Command, args, cwd and environment for the child process."""
+
+    # --- output handling --------------------------------------------------------------------
+
+    def _emit_filtered_traceback(self, on_log: Callable[[LogLevel, str], None]) -> None:
+        buf = self._traceback_buffer
+        if not buf:
+            return
+        exception_line = buf[-1]
+        user_frames: list[str] = []
+        for i in range(len(buf) - 1):
+            frame_line = buf[i]
+            if frame_line.lstrip().startswith("File ") and not _is_internal_frame(frame_line):
+                user_frames.append(frame_line)
+                nxt = buf[i + 1] if i + 1 < len(buf) else None
+                if nxt and nxt.startswith(" ") and not nxt.lstrip().startswith("File "):
+                    user_frames.append(nxt)
+        for frame in user_frames:
+            on_log("error", frame)
+        on_log("error", exception_line)
+
+    def _handle_stdout_line(self, line: str) -> None:
+        if line:
+            self.options.callbacks.on_log("info", line)
+
+    def _handle_stderr_line(self, line: str) -> None:
+        on_log = self.options.callbacks.on_log
+        if not line:
+            return
+        with self._lock:
+            self._recent_stderr.append(line)
+            if len(self._recent_stderr) > STDERR_BUFFER_SIZE:
+                self._recent_stderr.pop(0)
+            # Python tracebacks: buffer, then emit only user frames + the exception line.
+            if line.startswith("Traceback (most recent call last)"):
+                self._in_traceback = True
+                self._traceback_buffer = []
+            if self._in_traceback:
+                self._traceback_buffer.append(line)
+                is_stack_frame = line.startswith(" ") or line.startswith("File ")
+                if not is_stack_frame and not line.startswith("Traceback "):
+                    self._emit_filtered_traceback(on_log)
+                    self._in_traceback = False
+                    self._traceback_buffer = []
+                    self._recent_stderr = []
+                return
+        lower = line.lower()
+        if "warning" in lower:
+            on_log("warn", line)
+        elif "error" in lower:
+            on_log("error", line)
+        else:
+            on_log("info", line)
+
+    def _pump(self, stream, handle: Callable[[str], None]) -> None:  # type: ignore[no-untyped-def]
+        for raw in iter(stream.readline, b""):
+            text = raw.decode("utf-8", errors="replace").rstrip("\r\n")
+            for line in text.split("\n"):
+                handle(line.rstrip("\r"))
+        stream.close()
+
+    def _attach_handlers(self) -> None:
+        child = self.child
+        assert child is not None
+        readers = [
+            threading.Thread(target=self._pump, args=(child.stdout, self._handle_stdout_line), daemon=True),
+            threading.Thread(target=self._pump, args=(child.stderr, self._handle_stderr_line), daemon=True),
+        ]
+        for reader in readers:
+            reader.start()
+
+        def wait_exit() -> None:
+            returncode = child.wait()
+            for reader in readers:
+                reader.join(timeout=5)
+            self._clear_exit_cleanup()
+            code: int | None = None if returncode < 0 else returncode
+            on_log = self.options.callbacks.on_log
+            if code not in (0, None) and self._recent_stderr:
+                for line in self._recent_stderr:
+                    on_log("error", line)
+                self._recent_stderr = []
+            self.options.callbacks.on_exit(code)
+
+        threading.Thread(target=wait_exit, daemon=True).start()

agentcore/operations/dev/gateway_env.py

@@ -0,0 +1,25 @@
+"""Port of operations/dev/gateway-env.ts."""
+
+from agentcore.lib.schemas.io.config_io import ConfigIO
+
+
+def get_gateway_env_vars() -> dict[str, str]:
+    """``AGENTCORE_GATEWAY_<NAME>_URL`` / ``_AUTH_TYPE`` for every deployed gateway."""
+    env: dict[str, str] = {}
+    try:
+        config_io = ConfigIO()
+        state = config_io.read_deployed_state()
+        project = config_io.read_project_spec()
+        for target in (state.targets or {}).values():
+            resources = target.resources if target else None
+            mcp = resources.mcp if resources else None
+            for name, gateway in ((mcp.gateways if mcp else None) or {}).items():
+                if not gateway.gateway_url:
+                    continue
+                sanitized = name.upper().replace("-", "_")
+                env[f"AGENTCORE_GATEWAY_{sanitized}_URL"] = gateway.gateway_url
+                spec = next((g for g in project.agent_core_gateways or [] if g.name == name), None)
+                env[f"AGENTCORE_GATEWAY_{sanitized}_AUTH_TYPE"] = (spec.authorizer_type if spec else None) or "NONE"
+    except Exception:  # noqa: BLE001 - no deployed state or project spec issue: skip, as upstream
+        pass
+    return env