agentenv-framework 0.9.1254__py3-none-any.whl

agent_env/task_step/task_steps/deploy_env.py

@@ -0,0 +1,197 @@
+"""Deploy environment task step."""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from typing import ClassVar, Optional
+
+from agent_env.env.gateway import GatewayMode
+from agent_env.env.store import update_env_instance_metadata
+from agent_env.task_step.context import TaskStepContext
+from agent_env.entity_refs import EntityRef
+from agent_env.task_step.task_step import TaskStep, TaskStepDependency
+from agent_env.attribution import deploy_attribution
+
+logger = logging.getLogger(__name__)
+
+
+class DeployEnvTaskStep(TaskStep):
+    type: ClassVar[str] = "deploy_env"
+    entity_refs = (EntityRef.env("env_id", version_field="env_version"),)
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        env_id: str,
+        env_version: Optional[int] = None,
+        ttl_seconds: int = TaskStep.DEFAULT_TTL_SECONDS,
+        disk_size_gb: float = 10,
+        gateway_mode: str = GatewayMode.PERFORMANCE.value,
+        cpu: Optional[float] = None,
+        memory_mb: Optional[int] = None,
+        sandbox_type: Optional[str] = None,
+        priority: Optional[int] = None,
+        env_state_type: Optional[str] = None,
+        env_state_instance_id: Optional[str] = None,
+        depends_on: Optional[list[TaskStepDependency]] = None,
+        fail_task_on_error: bool = True,
+        metadata: Optional[dict] = None,
+    ):
+        super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error)
+        self.env_id = env_id
+        self.env_version = env_version
+        self.ttl_seconds = ttl_seconds
+        self.disk_size_gb = disk_size_gb
+        self.gateway_mode = gateway_mode
+        self.cpu = cpu
+        self.memory_mb = memory_mb
+        self.sandbox_type = sandbox_type
+        self.env_state_type = env_state_type
+        # Existing env state instance to attach to; the provider interprets it.
+        self.env_state_instance_id = env_state_instance_id
+        self.priority = priority
+        self.metadata = metadata or {}
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base["env_id"] = self.env_id
+        base["env_version"] = self.env_version
+        base["ttl_seconds"] = self.ttl_seconds
+        base["disk_size_gb"] = self.disk_size_gb
+        base["gateway_mode"] = self.gateway_mode
+        base["cpu"] = self.cpu
+        base["memory_mb"] = self.memory_mb
+        base["sandbox_type"] = self.sandbox_type
+        base["env_state_type"] = self.env_state_type
+        base["env_state_instance_id"] = self.env_state_instance_id
+        base["priority"] = self.priority
+        base["metadata"] = self.metadata
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict) -> DeployEnvTaskStep:
+        return cls(
+            **cls._base_from_dict(data),
+            env_id=data["env_id"],
+            env_version=data.get("env_version"),
+            ttl_seconds=data.get("ttl_seconds", TaskStep.DEFAULT_TTL_SECONDS),
+            disk_size_gb=data.get("disk_size_gb", 10),
+            gateway_mode=data.get("gateway_mode", GatewayMode.PERFORMANCE.value),
+            cpu=data.get("cpu"),
+            memory_mb=data.get("memory_mb"),
+            sandbox_type=data.get("sandbox_type"),
+            env_state_type=data.get("env_state_type"),
+            env_state_instance_id=data.get("env_state_instance_id"),
+            priority=data.get("priority"),
+            metadata=dict(data.get("metadata") or {}),
+        )
+
+    def preflight(self) -> list[str]:
+        """An invalid gateway_mode, an env this step can't load, or an option it would refuse at deploy, reported at save instead."""
+        from agent_env.env.env import Env
+        from agent_env.env.envs.mcp_server import MCPServerEnv
+        from agent_env.env.envs.multi_env import MultiEnv
+        from agent_env.env.envs.website import WebsiteEnv
+        from agent_env.store.base import NotFoundError
+
+        try:
+            GatewayMode(self.gateway_mode)
+        except ValueError as e:
+            return [f"deploy_env '{self.id}': {e}"]  # the words execute() would raise
+        try:
+            env = Env.get(self.env_id, self.env_version)
+            if not isinstance(env, (MCPServerEnv, WebsiteEnv, MultiEnv)):
+                return []
+            # As stored: run-time overrides aren't known at save, and deploy() consumes sandbox_type itself. Every run passes an
+            # attribution, so the check does too, whatever it will hold.
+            refusal = env.deploy_refusal(ttl_seconds=self.ttl_seconds, disk_size_gb=self.disk_size_gb, gateway_mode=self.gateway_mode, cpu=self.cpu,
+                                         memory_mb=self.memory_mb, priority=self.priority, env_state_type=self.env_state_type,
+                                         env_state_instance_id=self.env_state_instance_id, attribution={})
+        except (NotFoundError, ValueError) as e:  # missing, or a type or env_provider_type this process can't load
+            return [f"deploy_env '{self.id}': env '{self.env_id}' can't be loaded: {e}"]
+        return [f"deploy_env '{self.id}': {refusal}"] if refusal else []
+
+    async def execute(self, context: TaskStepContext) -> TaskStepContext:
+        from agent_env.env.env import Env
+
+        existing = next((d for d in context.deployed_envs if d.env_id == self.env_id), None)
+        if existing is not None:
+            raise RuntimeError(f"Env '{self.env_id}' is already deployed")
+
+        env = Env.get(self.env_id, self.env_version)
+        user_overrides = context.metadata.get("user_overrides", {})
+        resolved_sandbox_type = user_overrides.get("env_sandbox") or self.sandbox_type
+        resolved_env_state_type = user_overrides.get("env_state_type") or self.env_state_type
+        resolved_env_state_instance_id = (
+            user_overrides.get("env_state_instance_id") or self.env_state_instance_id
+        )
+        _priority_override = user_overrides.get("priority")
+        resolved_priority = _priority_override if _priority_override is not None else self.priority
+        _ttl_override = user_overrides.get("ttl_seconds")
+        resolved_ttl = _ttl_override if _ttl_override is not None else self.ttl_seconds
+        attribution = deploy_attribution(self, context)
+        logger.info(
+            f"Deploying env '{self.env_id}' (ttl={resolved_ttl}s, "
+            f"disk_size_gb={self.disk_size_gb}, gateway_mode={self.gateway_mode}, "
+            f"cpu={self.cpu}, memory_mb={self.memory_mb}, "
+            f"sandbox_type={resolved_sandbox_type}, env_state_type={resolved_env_state_type}, "
+            f"env_state_instance_id={resolved_env_state_instance_id}, "
+            f"attribution={attribution}, priority={resolved_priority})"
+        )
+        deploy_kwargs = {
+            "ttl_seconds": resolved_ttl,
+            "disk_size_gb": self.disk_size_gb,
+            "gateway_mode": GatewayMode(self.gateway_mode),
+            "cpu": self.cpu,
+            "memory_mb": self.memory_mb,
+            "priority": resolved_priority,
+            "attribution": attribution,
+        }
+        if resolved_sandbox_type is not None:
+            deploy_kwargs["sandbox_type"] = resolved_sandbox_type
+        if resolved_env_state_type is not None:
+            deploy_kwargs["env_state_type"] = resolved_env_state_type
+        if resolved_env_state_instance_id is not None:
+            deploy_kwargs["env_state_instance_id"] = resolved_env_state_instance_id
+        # Forward the per-run LiteLLM key so envs that spin up their own LLM-calling
+        # sidecars attribute spend to the same key as the agent. Guard on the
+        # signature — most envs' deploy() takes a fixed param list and would
+        # TypeError on an unexpected kwarg.
+        params = inspect.signature(env.deploy).parameters
+        accepts_kwargs = any(p.kind == inspect.Parameter.VAR_KEYWORD for p in params.values())
+        model_api_key = user_overrides.get("litellm_api_key")
+        if model_api_key and ("litellm_api_key" in params or accepts_kwargs):
+            deploy_kwargs["litellm_api_key"] = model_api_key
+        deployed_env = await env.deploy(**deploy_kwargs)
+        # create_instance runs inside env.deploy(), so an annotation set after it
+        # returns has to be persisted explicitly to reach the instance record.
+        annotations = {"deploy_step_id": self.id}
+        deployed_env.metadata = {**(deployed_env.metadata or {}), **annotations}
+        if deployed_env.instance_id:
+            update_env_instance_metadata(deployed_env.instance_id, annotations)
+        context.deployed_envs.append(deployed_env)
+
+        # Some envs (e.g. harbor coding tasks) build + run the agent as part of
+        # deploy() and have no separate DeployAgent step. They advertise the
+        # running agent via DeployedEnv.metadata["deployed_agent"]; register it
+        # so PromptAgent can resolve it by name from context.deployed_agents.
+        agent_info = (deployed_env.metadata or {}).get("deployed_agent")
+        if agent_info:
+            from agent_env.task_step.context import DeployedAgent
+
+            if any(a.agent_name == agent_info["agent_name"] for a in context.deployed_agents):
+                raise RuntimeError(
+                    f"Agent '{agent_info['agent_name']}' already in context.deployed_agents"
+                )
+            context.deployed_agents.append(DeployedAgent(
+                agent_name=agent_info["agent_name"],
+                api_url=agent_info["api_url"],
+                sandbox_id=agent_info.get("sandbox_id"),
+                sandbox_type=agent_info.get("sandbox_type"),
+                a2a_url=agent_info.get("a2a_url"),
+                a2a_card=agent_info.get("a2a_card"),
+                instance_id=agent_info.get("instance_id") or deployed_env.instance_id,
+            ))
+        return context

agent_env/task_step/task_steps/deploy_human_agent.py

@@ -0,0 +1,100 @@
+"""Register an external human A2A endpoint as a peerable DeployedAgent, so a
+single-turn solver can consult a human via the peer_send_message tool. A peer
+needs only a name + URL, so the card is best-effort.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar, Optional
+
+import httpx
+
+from agent_env.task_step.context import DeployedAgent, TaskStepContext
+from agent_env.task_step.task_step import TaskStep, TaskStepDependency
+
+logger = logging.getLogger(__name__)
+
+_CARD_FETCH_TIMEOUT_SECONDS = 5
+
+
+class DeployHumanAgentTaskStep(TaskStep):
+    type: ClassVar[str] = "deploy_human_agent"
+    entity_refs = ()
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        agent_name: str = "human_agent",
+        a2a_url: Optional[str] = None,
+        depends_on: Optional[list[TaskStepDependency]] = None,
+        fail_task_on_error: bool = True,
+    ):
+        super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error)
+        self.agent_name = agent_name
+        self.a2a_url = a2a_url
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base["agent_name"] = self.agent_name
+        base["a2a_url"] = self.a2a_url
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict) -> DeployHumanAgentTaskStep:
+        return cls(
+            **cls._base_from_dict(data),
+            agent_name=data.get("agent_name", "human_agent"),
+            a2a_url=data.get("a2a_url"),
+        )
+
+    async def execute(self, context: TaskStepContext) -> TaskStepContext:
+        from agent_env.config import get_config
+
+        if context.metadata.get("human_agents"):
+            raise RuntimeError(
+                "DeployHumanAgentTaskStep: a human agent is already registered; "
+                "only one human agent is allowed per task"
+            )
+        if any(a.agent_name == self.agent_name for a in context.deployed_agents):
+            raise RuntimeError(f"Agent with name '{self.agent_name}' is already deployed")
+
+        if self.a2a_url:
+            url = self.a2a_url
+        else:
+            base = get_config().get_default_human_a2a_url()
+            # Run-scope the URL so the human endpoint can attribute the ask to this
+            # task instance from the request path.
+            url = f"{base.rstrip('/')}/instance/{context.instance_id}" if context.instance_id else base
+        card = await self._resolve_card(url)
+
+        context.deployed_agents.append(
+            DeployedAgent(agent_name=self.agent_name, api_url=url, a2a_url=url, a2a_card=card)
+        )
+        context.metadata.setdefault("human_agents", []).append(
+            {"step_id": self.id, "agent_name": self.agent_name, "a2a_url": url}
+        )
+        logger.info(f"Registered human peer '{self.agent_name}' at {url} (card name={card.get('name')})")
+        return context
+
+    async def _resolve_card(self, url: str) -> dict:
+        """Best-effort card fetch — a human endpoint may not serve one, and a peer needs no card, so fall back to a synthesized card."""
+        try:
+            async with httpx.AsyncClient() as client:
+                resp = await client.get(f"{url}/.well-known/agent.json", timeout=_CARD_FETCH_TIMEOUT_SECONDS)
+            if resp.status_code == 200:
+                return resp.json()
+            logger.warning(f"Human agent card at {url} returned {resp.status_code}; using a synthesized card")
+        except Exception as e:
+            logger.warning(f"Could not fetch human agent card from {url} ({type(e).__name__}: {e}); using a synthesized card")
+        return self._synthesized_card()
+
+    def _synthesized_card(self) -> dict:
+        return {
+            "name": self.agent_name,
+            "description": "A human operator available to answer questions",
+            "capabilities": {},
+            "default_input_modes": ["text"],
+            "default_output_modes": ["text"],
+        }

agent_env/task_step/task_steps/deploy_sandbox.py

@@ -0,0 +1,170 @@
+"""Deploy bare sandbox task step."""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar, Optional
+
+from agent_env.providers.sandbox_providers.sandbox import NetworkPolicy
+from agent_env.task_step.context import DeployedSandbox, TaskStepContext
+from agent_env.task_step.task_step import TaskStep, TaskStepDependency
+from agent_env.attribution import deploy_attribution
+
+logger = logging.getLogger(__name__)
+
+_SUPPORTED_MODES = {"vm", "container"}
+
+
+class DeploySandboxTaskStep(TaskStep):
+    type: ClassVar[str] = "deploy_sandbox"
+    entity_refs = ()
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        sandbox_name: str,
+        sandbox_mode: str,
+        image: Optional[str] = None,
+        cpu: float = 2.0,
+        memory_mb: int = 8192,
+        disk_size_gb: float = 10,
+        ttl_seconds: int = TaskStep.DEFAULT_TTL_SECONDS,
+        exposed_ports: Optional[list[int]] = None,
+        boot_mode: Optional[str] = None,
+        port: Optional[int] = None,
+        env_vars: Optional[dict[str, str]] = None,
+        sandbox_type: Optional[str] = None,
+        priority: Optional[int] = None,
+        network_policy: Optional[dict] = None,
+        depends_on: Optional[list[TaskStepDependency]] = None,
+        fail_task_on_error: bool = True,
+        metadata: Optional[dict] = None,
+    ):
+        super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error)
+        if sandbox_mode not in _SUPPORTED_MODES:
+            raise ValueError(f"sandbox_mode must be one of {sorted(_SUPPORTED_MODES)}, got {sandbox_mode!r}")
+        self.sandbox_name = sandbox_name
+        self.sandbox_mode = sandbox_mode
+        self.image = image
+        self.cpu = cpu
+        self.memory_mb = memory_mb
+        self.disk_size_gb = disk_size_gb
+        self.ttl_seconds = ttl_seconds
+        self.exposed_ports = exposed_ports
+        self.boot_mode = boot_mode
+        self.port = port
+        self.env_vars = env_vars
+        self.sandbox_type = sandbox_type
+        self.priority = priority
+        self.metadata = metadata or {}
+        self.network_policy = NetworkPolicy.from_dict(network_policy).to_dict() if network_policy else None
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base["sandbox_name"] = self.sandbox_name
+        base["sandbox_mode"] = self.sandbox_mode
+        base["image"] = self.image
+        base["cpu"] = self.cpu
+        base["memory_mb"] = self.memory_mb
+        base["disk_size_gb"] = self.disk_size_gb
+        base["ttl_seconds"] = self.ttl_seconds
+        base["exposed_ports"] = self.exposed_ports
+        base["boot_mode"] = self.boot_mode
+        base["port"] = self.port
+        base["env_vars"] = self.env_vars
+        base["sandbox_type"] = self.sandbox_type
+        base["priority"] = self.priority
+        base["metadata"] = self.metadata
+        base["network_policy"] = self.network_policy
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict) -> DeploySandboxTaskStep:
+        return cls(
+            **cls._base_from_dict(data),
+            sandbox_name=data["sandbox_name"],
+            sandbox_mode=data["sandbox_mode"],
+            image=data.get("image"),
+            cpu=data.get("cpu", 2.0),
+            memory_mb=data.get("memory_mb", 8192),
+            disk_size_gb=data.get("disk_size_gb", 10),
+            ttl_seconds=data.get("ttl_seconds", TaskStep.DEFAULT_TTL_SECONDS),
+            exposed_ports=data.get("exposed_ports"),
+            boot_mode=data.get("boot_mode"),
+            port=data.get("port"),
+            env_vars=data.get("env_vars"),
+            sandbox_type=data.get("sandbox_type"),
+            priority=data.get("priority"),
+            metadata=dict(data.get("metadata") or {}),
+            network_policy=data.get("network_policy"),
+        )
+
+    async def execute(self, context: TaskStepContext) -> TaskStepContext:
+        from agent_env.providers.sandbox_providers.sandbox_provider import build_sandbox_provider, get_sandbox_provider
+
+        if any(s.sandbox_name == self.sandbox_name for s in context.deployed_sandboxes):
+            raise RuntimeError(f"Sandbox '{self.sandbox_name}' is already deployed")
+
+        user_overrides = context.metadata.get("user_overrides") or {}
+        # Moves only deploy_sandbox steps: deploy_env and deploy_agent read env_sandbox and agent_sandbox.
+        resolved_sandbox_type = user_overrides.get("sandbox") or self.sandbox_type
+        provider = (
+            build_sandbox_provider(resolved_sandbox_type)
+            if resolved_sandbox_type
+            else get_sandbox_provider()
+        )
+
+        _ttl_override = user_overrides.get("ttl_seconds")
+        resolved_ttl = _ttl_override if _ttl_override is not None else self.ttl_seconds
+        attribution = deploy_attribution(self, context)
+        logger.info(
+            f"Deploying sandbox '{self.sandbox_name}' (mode={self.sandbox_mode}, "
+            f"image={self.image}, cpu={self.cpu}, memory_mb={self.memory_mb}, "
+            f"disk_size_gb={self.disk_size_gb}, ttl_seconds={resolved_ttl}, "
+            f"sandbox_type={resolved_sandbox_type}, attribution={attribution})"
+        )
+
+        _override = user_overrides.get("network_policy")
+        _resolved = _override if _override is not None else self.network_policy
+        policy = NetworkPolicy.from_dict(_resolved) if _resolved is not None else None
+
+        if self.sandbox_mode == "vm":
+            sandbox = await provider.create_vm(
+                image=self.image,
+                boot_mode=self.boot_mode,
+                cpu=self.cpu,
+                memory=self.memory_mb,
+                disk_size_gb=self.disk_size_gb,
+                timeout=resolved_ttl,
+                exposed_ports=self.exposed_ports or [],
+                attribution=attribution,
+                priority=self.priority,
+                network_policy=policy,
+            )
+        else:
+            if self.image is None or self.port is None:
+                raise ValueError("container-mode sandbox requires `image` and `port`")
+            sandbox = await provider.create_sandbox(
+                image_name=self.image,
+                port=self.port,
+                env=self.env_vars or {},
+                cpu=self.cpu,
+                memory=self.memory_mb,
+                disk_size_gb=self.disk_size_gb,
+                timeout=resolved_ttl,
+                attribution=attribution,
+                priority=self.priority,
+                network_policy=policy,
+            )
+
+        context.deployed_sandboxes.append(DeployedSandbox(
+            sandbox_name=self.sandbox_name,
+            sandbox_id=sandbox.sandbox_id,
+            sandbox_mode=sandbox.mode,
+            sandbox_type=sandbox.type,
+            tunnel_urls={str(p): u for p, u in sandbox.tunnel_urls.items()} if sandbox.tunnel_urls else None,
+            vnc_url=sandbox.vnc_url,
+            network_policy=sandbox.network_policy.to_dict() if sandbox.network_policy else None,
+        ))
+        return context

agent_env/task_step/task_steps/env_card_validator/__init__.py

@@ -0,0 +1,4 @@
+from .verify_env_card import ENVIRONMENT_CARD_KEY, VALIDATED_ENVIRONMENT_CARD_KEY, VerifyEnvironmentCardStep
+from .verify_env_core_protocol import VALIDATED_ENVIRONMENT_PROTOCOL_KEY, VerifyCoreEnvironmentProtocolStep
+
+__all__ = ["VerifyEnvironmentCardStep", "VerifyCoreEnvironmentProtocolStep", "ENVIRONMENT_CARD_KEY", "VALIDATED_ENVIRONMENT_CARD_KEY", "VALIDATED_ENVIRONMENT_PROTOCOL_KEY"]

agent_env/task_step/task_steps/env_card_validator/verify_env_card.py

@@ -0,0 +1,109 @@
+"""Verify the EnvironmentCard a deployed environment serves at its card's address, and persist it to env metadata."""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar, Optional
+
+from agent_env.task_step.context import TaskStepContext
+from agent_env.entity_refs import EntityRef
+from agent_env.task_step.task_step import TaskStep, TaskStepDependency
+
+logger = logging.getLogger(__name__)
+
+REQUIRED_CARD_FIELDS = ["name", "protocolVersion", "url", "preferredTransport", "capabilities"]
+
+# Env-doc metadata keys the validator writes (read back by the CLIs / hub consumers).
+ENVIRONMENT_CARD_KEY = "environment_card"
+VALIDATED_ENVIRONMENT_CARD_KEY = "validated_environment_card"
+
+
+class VerifyEnvironmentCardStep(TaskStep):
+    type: ClassVar[str] = "verify_env_card"
+    entity_refs = (EntityRef.env("env_id"),)
+
+    def __init__(
+        self,
+        id: str,
+        version: Optional[int],
+        env_id: str,
+        depends_on: Optional[list[TaskStepDependency]] = None,
+        fail_task_on_error: bool = True,
+    ):
+        super().__init__(id, version, depends_on=depends_on, fail_task_on_error=fail_task_on_error)
+        self.env_id = env_id
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base["env_id"] = self.env_id
+        return base
+
+    @classmethod
+    def from_dict(cls, data: dict) -> VerifyEnvironmentCardStep:
+        return cls(**cls._base_from_dict(data), env_id=data["env_id"])
+
+    async def execute(self, context: TaskStepContext) -> TaskStepContext:
+        from agentenv_protocol import client as protocol_v1
+        from agent_env.env.env import Env
+
+        deployed = next((d for d in context.deployed_envs if d.env_id == self.env_id), None)
+        if deployed is None:
+            raise RuntimeError(f"Env '{self.env_id}' not found in context.deployed_envs")
+
+        card = None
+        error = None
+        try:
+            card = await protocol_v1.get_card(deployed.environment_url)
+        except Exception as e:
+            error = f"{type(e).__name__}: {e}"
+            logger.warning(f"env card for '{self.env_id}' inaccessible at {deployed.environment_url}: {error}")
+
+        env = Env.get(self.env_id, deployed.env_version)
+
+        if not card:
+            validated = {"accessible": False, "error": error or "empty card"}
+            env.update_metadata({**env.metadata, VALIDATED_ENVIRONMENT_CARD_KEY: validated})
+            context.metadata.setdefault("verifications", {})["environment_card"] = {VALIDATED_ENVIRONMENT_CARD_KEY: validated}
+            return context
+
+        required_fields = {}
+        missing_required = []
+        for field in REQUIRED_CARD_FIELDS:
+            present = field in card and bool(card[field])
+            required_fields[field] = {"present": present}
+            if not present:
+                missing_required.append(field)
+        if missing_required:
+            logger.warning(f"env card '{self.env_id}' missing required fields: {missing_required}")
+
+        children = card.get("children_environments") or []
+        capabilities = card.get("capabilities") or {}
+        extensions = [uri for e in capabilities.get("extensions") or [] if (uri := e.get("uri"))]
+        tools = [name for t in capabilities.get("tools") or [] if (name := t.get("name"))]
+        logger.info(f"env card '{self.env_id}': name={card.get('name')} children={len(children)} extensions={extensions} tools={tools}")
+
+        registered_name = getattr(env, "environment_name", None)
+        served_names = [c.get("name") for c in children if c.get("name")]
+        name_check = None
+        if registered_name and served_names:
+            matches = registered_name in served_names
+            name_check = {"registered_name": registered_name, "served_card_names": served_names, "matches": matches}
+            if not matches:
+                logger.warning(
+                    f"env card name drift for '{self.env_id}': registered environment_name={registered_name!r} is not "
+                    f"among the served card names {served_names!r} — the image's agentenv-protocol likely predates "
+                    f"ENVIRONMENT_NAME taking precedence over @environment_card(name=...); rebuild it on a current SDK."
+                )
+
+        validated = {
+            "accessible": True,
+            "required_fields": required_fields,
+            "children_count": len(children),
+            "extensions": extensions,
+            "tools": tools,
+            "name_check": name_check,
+        }
+        env.update_metadata({**env.metadata, ENVIRONMENT_CARD_KEY: card, VALIDATED_ENVIRONMENT_CARD_KEY: validated})
+
+        context.metadata.setdefault("verifications", {})["environment_card"] = {ENVIRONMENT_CARD_KEY: card, VALIDATED_ENVIRONMENT_CARD_KEY: validated}
+        return context