agentenv-framework-protocol 0.1.495__tar.gz → 0.1.497__tar.gz

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.495
+Version: 0.1.497
 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
@@ -265,7 +265,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

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/README.md

@@ -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

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/pyproject.toml

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

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/src/agentenv_protocol/client.py

@@ -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]:
@@ -258,7 +266,8 @@ class ChildEnv:
 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)]
 
 
@@ -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")
@@ -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
 

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/src/agentenv_protocol/types.py

@@ -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()

{agentenv_framework_protocol-0.1.495 → agentenv_framework_protocol-0.1.497}/tests/test_client.py

@@ -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