agentenv-framework-protocol 0.1.454__tar.gz → 0.1.455__tar.gz

{agentenv_framework_protocol-0.1.454 → agentenv_framework_protocol-0.1.455}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.454
+Version: 0.1.455
 Summary: Open data-plane protocol and server SDK for agent environments.
 Project-URL: Homepage, https://www.agentenvframework.com
 Project-URL: Documentation, https://www.agentenvframework.com/docs
@@ -258,6 +258,16 @@ with any other transport are kept beside the SDK's entry. Card URLs are paths, r
 address the card was fetched from. On the client side, `client.mcp_path(card)` returns the
 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.
+`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
+server can, so `client.child_at(card, url)` finds one by its url or route; `client.child_named(card,
+name)` raises `AmbiguousChildError` for a shared name, and `client.find_child` returns the first.
+`client.serves(card, method)` says whether a card serves a data-plane method by its declared
+`operations`, None for a card that declares none.
+
 Extensions are invoked from what the card advertises. `client.find_extension_method(card, uri,
 method)` returns one advertised method, whose `endpoint` is the method's own or else the
 extension's, and `client.invoke_extension(base_url, card, uri, params, method=...)` calls it with

{agentenv_framework_protocol-0.1.454 → agentenv_framework_protocol-0.1.455}/README.md

@@ -199,6 +199,16 @@ with any other transport are kept beside the SDK's entry. Card URLs are paths, r
 address the card was fetched from. On the client side, `client.mcp_path(card)` returns the
 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.
+`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
+server can, so `client.child_at(card, url)` finds one by its url or route; `client.child_named(card,
+name)` raises `AmbiguousChildError` for a shared name, and `client.find_child` returns the first.
+`client.serves(card, method)` says whether a card serves a data-plane method by its declared
+`operations`, None for a card that declares none.
+
 Extensions are invoked from what the card advertises. `client.find_extension_method(card, uri,
 method)` returns one advertised method, whose `endpoint` is the method's own or else the
 extension's, and `client.invoke_extension(base_url, card, uri, params, method=...)` calls it with

{agentenv_framework_protocol-0.1.454 → agentenv_framework_protocol-0.1.455}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "agentenv-framework-protocol"
-version = "0.1.454"
+version = "0.1.455"
 description = "Open data-plane protocol and server SDK for agent environments."
 readme = "README.md"
 license = "Apache-2.0"

{agentenv_framework_protocol-0.1.454 → agentenv_framework_protocol-0.1.455}/src/agentenv_protocol/client.py

@@ -7,6 +7,7 @@ import contextlib
 import logging
 from collections.abc import Iterator
 from contextvars import ContextVar
+from dataclasses import dataclass, field
 
 import httpx
 
@@ -210,6 +211,83 @@ def find_tool(card: dict, name: str) -> dict | None:
     return None
 
 
+def serves(card: dict, method: str) -> bool | None:
+    """Whether a card serves the data-plane ``method`` (``data/get`` say): True or False by its declared
+    ``capabilities.operations``, or None when it declares none, as an older card doesn't, so the caller decides as it
+    did before cards declared them (a probe, say)."""
+    declared = operations(card)
+    return None if declared is None else method in declared
+
+
+@dataclass(frozen=True)
+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."""
+
+    name: str | None
+    url: str | None
+    card: dict = field(hash=False, repr=False)
+
+    @property
+    def extensions(self) -> list[dict]:
+        """The extensions the child's card advertises (``capabilities.extensions``)."""
+        return list((self.card.get("capabilities") or {}).get("extensions") or [])
+
+    @property
+    def operations(self) -> list[str] | None:
+        """The data-plane methods the child's card declares (``operations``), or None when it declares none."""
+        return operations(self.card)
+
+    def find_extension(self, uri: str) -> dict | None:
+        """The extension the child's card advertises under ``uri``, or None (``find_extension``)."""
+        return find_extension(self.card, uri)
+
+    def serves(self, method: str) -> bool | None:
+        """Whether the child's card serves the data-plane ``method``, None when it declares no operations (``serves``)."""
+        return serves(self.card, method)
+
+    def base_url(self, address: str) -> str:
+        """Where the child's data plane is, its ``url`` without the RPC path, resolved against ``address``, the composed
+        card's: a path joins onto it, a full URL stands alone, and a child naming no url is at ``address`` itself."""
+        url = (self.url or RPC_PATH).removesuffix(RPC_PATH)
+        return url if "://" in url else f"{address.rstrip('/')}{url}"
+
+
+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)
+            for child in card.get("children_environments") or [] if isinstance(child, dict)]
+
+
+def child_at(card: dict, url: str) -> ChildEnv | None:
+    """The child env of a composed card at ``url``: the one whose ``url`` is ``url``, or whose data plane is there
+    (``url`` without the RPC path, ``/svc/mcp-slack`` for ``/svc/mcp-slack/agentenv`` say), a trailing slash aside;
+    None when no child is. A composer serves each child at its own route, so this is the lookup two children sharing a
+    name can't confuse."""
+    wanted = url.rstrip("/")
+    for child in children(card):
+        if child.url is not None and wanted in (child.url.rstrip("/"), child.url.removesuffix(RPC_PATH).rstrip("/")):
+            return child
+    return None
+
+
+class AmbiguousChildError(LookupError):
+    """More than one child env of a composed card has the name asked for, so the name can't say which is meant."""
+
+
+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]
+    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")
+    return found[0] if found else None
+
+
 def find_child(card: dict, name: str) -> dict | None:
     """Return the nested child EnvironmentCard named `name`, or None.
 
@@ -218,6 +296,8 @@ def find_child(card: dict, name: str) -> dict | None:
     rewritten to be reachable from the composed card's base_url. Callers resolve a service by
     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.
     """
     for child in card.get("children_environments") or []:
         if child.get("name") == name:

{agentenv_framework_protocol-0.1.454 → agentenv_framework_protocol-0.1.455}/tests/test_client.py

@@ -190,6 +190,58 @@ def test_find_child_tolerates_missing_children():
     assert protocol_v1.find_child({"children_environments": None}, "slack") is None
 
 
+_SHARED_NAME = {"name": "gw", "children_environments": [
+    {"name": "mail", "url": "/svc/mcp-mail/agentenv", "capabilities": {"operations": ["data/get"], "extensions": [
+        {"uri": "urn:agentenv:clock/v1"}]}},
+    {"name": "mail", "url": "/svc/mail/agentenv", "capabilities": {"operations": []}},
+    {"name": "docs", "capabilities": {}},
+    "not a card",
+]}
+
+
+def test_children_are_each_nested_card_by_its_name_url_and_card():
+    found = protocol_v1.children(_SHARED_NAME)
+
+    assert [(c.name, c.url) for c in found] == [("mail", "/svc/mcp-mail/agentenv"), ("mail", "/svc/mail/agentenv"), ("docs", None)]
+    assert found[0].card is _SHARED_NAME["children_environments"][0]
+    assert [c.extensions for c in found] == [[{"uri": "urn:agentenv:clock/v1"}], [], []]
+    assert [c.operations for c in found] == [["data/get"], [], None]
+    assert [c.serves("data/get") for c in found] == [True, False, None]
+    assert found[0].find_extension("urn:agentenv:clock/v1") is not None and found[1].find_extension("urn:agentenv:clock/v1") is None
+    assert protocol_v1.children({"name": "leaf"}) == [] and protocol_v1.children({"children_environments": None}) == []
+
+
+def test_a_childs_base_url_is_its_url_without_the_rpc_path_against_the_composed_cards_address():
+    mcp, website, docs = protocol_v1.children(_SHARED_NAME)
+
+    assert mcp.base_url("https://env.example/") == "https://env.example/svc/mcp-mail"
+    assert website.base_url("https://env.example") == "https://env.example/svc/mail"
+    assert docs.base_url("https://env.example") == "https://env.example"
+    assert protocol_v1.ChildEnv("x", "https://x.example/agentenv", {}).base_url("https://env.example") == "https://x.example"
+
+
+def test_child_at_finds_a_child_by_its_url_or_data_plane_route_where_two_share_a_name():
+    assert protocol_v1.child_at(_SHARED_NAME, "/svc/mail").url == "/svc/mail/agentenv"
+    assert protocol_v1.child_at(_SHARED_NAME, "/svc/mcp-mail/").url == "/svc/mcp-mail/agentenv"
+    assert protocol_v1.child_at(_SHARED_NAME, "/svc/mail/agentenv").url == "/svc/mail/agentenv"
+    assert protocol_v1.child_at(_SHARED_NAME, "/svc/docs") is None
+    assert protocol_v1.child_at({"name": "leaf"}, "/svc/mail") is None
+
+
+def test_child_named_refuses_a_name_two_children_share():
+    assert protocol_v1.child_named(_SHARED_NAME, "docs").name == "docs"
+    assert protocol_v1.child_named(_SHARED_NAME, "gmail") is None
+    with pytest.raises(protocol_v1.AmbiguousChildError, match="2 child envs are named 'mail'"):
+        protocol_v1.child_named(_SHARED_NAME, "mail")
+    assert protocol_v1.find_child(_SHARED_NAME, "mail")["url"] == "/svc/mcp-mail/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
+    assert protocol_v1.serves({"capabilities": {}}, "data/get") is None
+
+
 def test_find_extension_ignores_children():
     # set-errors/v1 is advertised only on the children, never at the top level
     assert protocol_v1.find_extension(_CARD_WITH_CHILDREN, "urn:agentenv:set-errors/v1") is None