Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -200,7 +200,10 @@ address the card was fetched from. On the client side, `client.mcp_path(card)` r
declared path, or `/mcp` for a card without one.

A composed card, such as a gateway's, nests each backing environment's card under
`children_environments`, its `url` and endpoints rooted at the route the composer serves it at.
`children_environments`, its `url` and endpoints rooted at the route the composer serves it at,
and its `environment_name`: the name the child env is registered as, which its own card's `name`
needn't be. A lookup by name finds a child by its `environment_name`, else, from a composer that
states none, by its card's `name` (`ChildEnv.known_as`).
`client.children(card)` returns each as a `ChildEnv` (its `name`, `url` and `card`, with its
`extensions`, `operations` and `serves(method)`, and `base_url(address)`, its data plane resolved
against the composed card's address). Two children may share a name, as a website and an MCP
Expand Down
25 changes: 18 additions & 7 deletions packages/agentenv-protocol/src/agentenv_protocol/client.py
Original file line number Diff line number Diff line change
Expand Up @@ -224,11 +224,19 @@ class ChildEnv:
"""One child env a composed card nests under ``children_environments``: its ``name`` and ``url`` as its card gives
them, and that ``card``, which says what it offers. A composer roots each child's ``url`` (and its endpoints) at
the route it serves the child at, so two children sharing a name have distinct urls; ``url`` is None for a child
whose card names none."""
whose card names none. ``environment_name`` is the name the composer states the child is registered as, None
from a composer that states none."""

name: str | None
url: str | None
card: dict = field(hash=False, repr=False)
environment_name: str | None = None

@property
def known_as(self) -> str | None:
"""The name a lookup finds the child by: the ``environment_name`` its composer states, else its card's
``name``, which an env built on this SDK serves its environment name as."""
return self.environment_name or self.name

@property
def extensions(self) -> list[dict]:
Expand Down Expand Up @@ -258,7 +266,8 @@ def base_url(self, address: str) -> str:
def children(card: dict) -> list[ChildEnv]:
"""Each child env a composed card nests under ``children_environments``, in its order; none for a leaf card, or
one whose ``children_environments`` is missing or null. An entry that isn't an object is skipped."""
return [ChildEnv(name=child.get("name"), url=child.get("url"), card=child)
return [ChildEnv(name=child.get("name"), url=child.get("url"), card=child,
environment_name=child.get("environment_name"))
for child in card.get("children_environments") or [] if isinstance(child, dict)]


Expand All @@ -279,9 +288,10 @@ class AmbiguousChildError(LookupError):


def child_named(card: dict, name: str) -> ChildEnv | None:
"""The one child env of a composed card named ``name``, or None when none is; raises ``AmbiguousChildError`` when
several are, as a website and an MCP server sharing a name are, which ``child_at`` tells apart by their urls."""
found = [child for child in children(card) if child.name == name]
"""The one child env of a composed card known as ``name`` (``ChildEnv.known_as``), or None when none is; raises
``AmbiguousChildError`` when several are, as a website and an MCP server sharing a name are, which ``child_at``
tells apart by their urls."""
found = [child for child in children(card) if child.known_as == name]
if len(found) > 1:
raise AmbiguousChildError(f"{len(found)} child envs are named {name!r} ({', '.join(str(c.url) for c in found)}); "
"look one up by its url")
Expand All @@ -297,10 +307,11 @@ def find_child(card: dict, name: str) -> dict | None:
name here, then use the child card with `find_extension`/`invoke_extension`. Tolerates a
missing/null `children_environments` so single/leaf cards return None rather than raising.
Two children sharing `name` return the first; `child_named` refuses that, and `child_at`
finds a child by its url, which tells them apart.
finds a child by its url, which tells them apart. A child is known by the `environment_name`
its composer states, else by its card's `name`.
"""
for child in card.get("children_environments") or []:
if child.get("name") == name:
if isinstance(child, dict) and (child.get("environment_name") or child.get("name")) == name:
return child
return None

Expand Down
2 changes: 2 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/types.py
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,8 @@ class EnvironmentCard(BaseModel):
additionalInterfaces: list[EnvironmentInterface] = Field(default_factory=list)
capabilities: EnvironmentCapabilities = Field(default_factory=EnvironmentCapabilities)
children_environments: Optional[list[EnvironmentCard]] = None
# Set by a composer on each child it nests: the name the child env is registered as, which its own name needn't be.
environment_name: Optional[str] = None


EnvironmentCard.model_rebuild()
16 changes: 16 additions & 0 deletions packages/agentenv-protocol/tests/test_client.py
Original file line number Diff line number Diff line change
Expand Up @@ -250,6 +250,22 @@ def test_child_named_refuses_a_name_two_children_share():
assert protocol_v1.find_child(_SHARED_NAME, "mail")["url"] == "/svc/mcp-mail/agentenv"


_STATED = {"name": "gw", "children_environments": [
{"name": "Notes", "url": "/svc/notes/agentenv", "environment_name": "notes"},
{"name": "slack", "url": "/svc/mcp-slack/agentenv"},
]}


def test_a_child_is_known_by_the_environment_name_its_composer_states_else_by_its_cards_name():
notes, slack = protocol_v1.children(_STATED)
assert (notes.name, notes.environment_name, notes.known_as) == ("Notes", "notes", "notes")
assert (slack.environment_name, slack.known_as) == (None, "slack") # a composer that states none
assert protocol_v1.child_named(_STATED, "notes").url == "/svc/notes/agentenv"
assert protocol_v1.child_named(_STATED, "Notes") is None
assert protocol_v1.find_child(_STATED, "notes")["name"] == "Notes"
assert protocol_v1.find_child(_STATED, "slack")["url"] == "/svc/mcp-slack/agentenv"


def test_serves_is_what_a_card_declares_of_a_method_and_none_when_it_declares_no_operations():
assert protocol_v1.serves({"capabilities": {"operations": ["data/get"]}}, "data/get") is True
assert protocol_v1.serves({"capabilities": {"operations": ["data/add"]}}, "data/get") is False
Expand Down
4 changes: 2 additions & 2 deletions src/agent_env/env/env.py
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,7 @@ def child_env(self, environment_name: str, *, mcp: Optional[bool] = None) -> Opt
composed = isinstance(card.get("children_environments"), list)
if (not composed or protocol_v1.operations(card)) and card.get("name") == environment_name:
return protocol_v1.ChildEnv(name=card.get("name"), url=card.get("url"), card=card)
found = [child for child in protocol_v1.children(card) if child.name == environment_name]
found = [child for child in protocol_v1.children(card) if child.known_as == environment_name]
if len(found) > 1 and mcp is not None:
found = [child for child in found if website_child(child) is not mcp]
if len(found) > 1:
Expand Down Expand Up @@ -514,7 +514,7 @@ async def load_file_artifact_universe(
def website_child(child: protocol_v1.ChildEnv) -> bool:
"""Whether a child env is a website: its card carries ``website/v1``, or, for a site serving none, its url is at a
website's gateway route, ``/svc/{name}`` (an MCP server's is ``/svc/mcp-{name}``)."""
route, url = f"/svc/{child.name}", (child.url or "").rstrip("/")
route, url = f"/svc/{child.known_as}", (child.url or "").rstrip("/")
return child.find_extension(WEBSITE_EXTENSION_URI) is not None or url == route or url.startswith(f"{route}/")


Expand Down
7 changes: 5 additions & 2 deletions src/agent_env/env/envs/computer/utils/sites.py
Original file line number Diff line number Diff line change
Expand Up @@ -590,8 +590,11 @@ def _env_qualified(found: list[tuple[str, dict]]) -> list[dict]:


def _served_as(child) -> str:
"""The gateway service a child env is served as: the ``<name>`` of the ``/svc/<name>/`` route its url is at, which
``website_frontend_urls`` keys it by, else its card's name."""
"""The name a website child env is served as, which ``website_frontend_urls`` keys it by: the environment_name its
gateway states; from a gateway that states none, the ``<name>`` of the ``/svc/<name>/`` route its url is at, else
its card's name."""
if child.environment_name:
return child.environment_name
parts = urlsplit(child.url or "").path.strip("/").split("/")
return parts[1] if len(parts) > 1 and parts[0] == "svc" and parts[1] else child.name

Expand Down
31 changes: 30 additions & 1 deletion src/agent_env/env/gateway/gateway.py
Original file line number Diff line number Diff line change
Expand Up @@ -797,10 +797,17 @@ def _backing_keys(self) -> list[str]:
# backends). Non-v1 backers (e.g. the injected website_browser) self-omit from the card via 404.
return list(self.rest_proxy_urls)

def _environment_name(self, key: str) -> str:
"""The name the env behind the backing server ``key`` is registered as (``route_environment_name``)."""
return route_environment_name(key, self.rest_proxy_urls.get(key, ""), self.internal_mcp_servers,
website=key in self.website_urls)

def _rewrite_child_card(self, key: str, card: dict) -> dict:
"""One backing server's card rooted at the gateway (``rewrite_child_card``); a website's ``website/v1`` params
"""One backing server's card rooted at the gateway (``rewrite_child_card``), stating the ``environment_name``
the env behind it is registered as, which its own card's name needn't be; a website's ``website/v1`` params
also name the route the gateway serves it to a browser at, ``/website/<key>/``, as ``browse_url``."""
card = rewrite_child_card(key, card, self._gateway_extensions())
card["environment_name"] = self._environment_name(key)
if key in self.website_urls:
for ext in (card.get("capabilities") or {}).get("extensions") or []:
if isinstance(ext, dict) and ext.get("uri") == EXT_WEBSITE_URI:
Expand Down Expand Up @@ -1468,6 +1475,28 @@ def reserved_site_path(path: str, reserved: frozenset[str] = frozenset()) -> boo
for base in (RPC_PATH, *reserved))


def route_environment_name(key: str, base_url: str, servers: list[InternalMCPServer], *, website: bool) -> str:
"""The name the env behind the backing server ``key``, at ``base_url``, is registered as. A website's key is its
name. Any other key is an MCP server's route, ``mcp-<name>``, or a child env's own name, a computer's, which may
start ``mcp-`` too; the internal MCP server whose endpoint is at the route's backend says which: one under the
route's base address first, else one on its host, as a server whose card is on another port than its MCP endpoint
is. With no such server, an ``mcp-`` key is an MCP server's route."""
stripped = key.removeprefix("mcp-")
if website or stripped == key:
return key
base = base_url.rstrip("/")
host = urlsplit(base).hostname

def at_backend(name: str) -> int:
urls = [server.mcp_url for server in servers if server.name == name]
if any(url.startswith(f"{base}/") for url in urls) and base:
return 2
return 1 if host and any(urlsplit(url).hostname == host for url in urls) else 0

route, own = at_backend(stripped), at_backend(key)
return key if own > route else stripped


def site_mcp_endpoints(servers: list[InternalMCPServer], website_urls: dict[str, str],
rest_proxy_urls: dict[str, str]) -> dict[str, str]:
"""The MCP endpoint, as a path under its /svc/<name>/ base, of each site that is an internal MCP server too, by
Expand Down
2 changes: 1 addition & 1 deletion src/agent_env/env/legacy_protocol.py
Original file line number Diff line number Diff line change
Expand Up @@ -98,7 +98,7 @@ def card_servers(card: dict, address: str) -> list[BackingServer]:
def _listed(child: protocol_v1.ChildEnv, address: str) -> BackingServer:
from agent_env.env.env import website_child

return BackingServer(child.name, mcp=not website_child(child), child=child, address=address)
return BackingServer(child.known_as, mcp=not website_child(child), child=child, address=address)


async def backing_servers(deployed: Optional[DeployedEnv], gateway_url: Optional[str], env: Any,
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ async def _resolve_manifest_endpoint(gateway_url: str, environment_name: str) ->
logger.debug("env card for %r unavailable (%s); constructing the manifest path", environment_name, e)
return None

found = [child for child in protocol_v1.children(card) if child.name == environment_name and not website_child(child)]
found = [child for child in protocol_v1.children(card) if child.known_as == environment_name and not website_child(child)]
if len(found) != 1:
logger.debug("env card has %s MCP server child named %r; constructing the manifest path",
len(found) or "no", environment_name)
Expand Down
13 changes: 13 additions & 0 deletions tst/integration/computer/multi_env_computers_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@

import httpx
import pytest
from agentenv_protocol import client as protocol_v1
from agentenv_protocol.tool_access import (DISABLE, DISABLE_TOOL_EXTENSION_URI, ENABLE, ENABLE_TOOL_EXTENSION_URI,
WILDCARD)
from agentenv_protocol.tool_context import DEFAULT_ROLE
Expand All @@ -34,6 +35,7 @@
from agent_env.env.envs.multi_env import MultiEnv
from agent_env.env.envs.playwright_mcp import PLAYWRIGHT_MCP_ENVIRONMENT_NAME
from agent_env.env.envs.website import WebsiteEnv
from agent_env.env.legacy_protocol import card_servers
from agent_env.providers.env_providers.env_gateway_provider import EnvironmentGatewayProvider
from agent_env.providers.sandbox_providers.local_docker.provider import LocalSandboxProvider
from agent_env.store.routing import namespace_routing
Expand Down Expand Up @@ -185,6 +187,10 @@ async def test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its
[deployed] = (await step.execute(context)).deployed_envs
computer = deployed.child_envs["desktop"]
listed, shot = await _tools(deployed)
stated = {child.environment_name: child.name for child in protocol_v1.children(deployed.environment_card)}
site = deployed.child_env("shop", mcp=False)
servers = {(server.environment_name, server.mcp)
for server in card_servers(deployed.environment_card, deployed.environment_url)}
async with httpx.AsyncClient(timeout=30) as client:
card = (await client.get(f"{deployed.gateway_url}/svc/desktop{WELL_KNOWN_PATH}")).json()
# Load, snapshot and reset reach the computer through the multi env, beside its MCP server.
Expand Down Expand Up @@ -230,6 +236,13 @@ async def test_a_computer_in_a_multi_env_is_served_through_its_gateway_under_its
assert json.dumps(deployed.child_envs) # the record stores as JSON
assert note == "from the universe" and "snap-x" in listed_items
assert {"items", "desktop"} <= set(snapshot) and snapshot["desktop"]["Documents/note.txt"] == b"from the universe"
# The gateway states each child's environment_name, which lookups, servers and snapshots go by: the shop
# website's card is named webitems.
assert {name: stated.get(name) for name in ("items", "shop", "desktop")} == {
"items": "items", "shop": "webitems", "desktop": "desktop"}, stated
assert site is not None and site.url.startswith("/svc/shop/"), site
assert {("items", True), ("shop", False)} <= servers and not any(name == "webitems" for name, _ in servers), servers
assert "shop" in snapshot and "webitems" not in snapshot, sorted(snapshot)
assert after_reset == "gone" and all(reset_answers.values()), reset_answers
assert computer["metadata"]["computer"]["sites"]["names"]["routes"] == {"shop": ["shop.test"]}
assert routed == routed_after_reset == "200"
Expand Down
22 changes: 22 additions & 0 deletions tst/unit/env/envs/test_computer_sites.py
Original file line number Diff line number Diff line change
Expand Up @@ -509,6 +509,28 @@ def child(served: str, domain: str) -> dict:
{"name": "Site", "url": "https://gw.example/website/blog/", "domains": ["blog.test"]}] # alone, its card's name


@pytest.mark.asyncio
async def test_a_website_is_selected_by_the_environment_name_its_gateway_states(monkeypatch):
from agentenv_protocol import client as protocol_v1

from agent_env.env.env import DeployedGatewayEnv

async def get_card(url, timeout=10, verify=True):
raise AssertionError(f"read {url} live")

monkeypatch.setattr(protocol_v1, "get_card", get_card)
card = {"name": "env", "children_environments": [{
"name": "Notes", "url": "/sites/notes-v2/agentenv", "environment_name": "notes", "capabilities": {
"extensions": [{"uri": "urn:agentenv:website/v1", "params": {"domains": ["notes.test"]}}]}}]}
gateway = DeployedGatewayEnv(env_id="sites", env_version=1, sandbox_id="s", gateway_url="https://gw.example",
environment_card=card,
website_frontend_urls={"notes": "https://gw.example/website/notes/"})

found = [{"name": "Notes", "url": "https://gw.example/website/notes/", "domains": ["notes.test"]}]
assert await sites.deployed_sites([gateway], services=["notes"]) == found # not the path's notes-v2
assert await sites.deployed_sites([gateway], services=["notes-v2"]) == []


@pytest.mark.asyncio
async def test_a_card_that_fails_to_load_is_retried_then_fails_rather_than_dropping_the_sites_names(monkeypatch):
from agentenv_protocol import client as protocol_v1
Expand Down
Loading
Loading