agentenv-framework-protocol 0.1.468__tar.gz → 0.1.469__tar.gz

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.468
+Version: 0.1.469
 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
@@ -524,6 +524,31 @@ print(env.ready, env.problems)                    # False ['shop: seeded']
   asked, or answers no `WebsiteReadiness`, is a problem itself. A card or child without `ready`, an MCP server's or an
   older site's, isn't counted, so an env with no site serving it is ready with no problems.
 
+## Websites with tools
+
+A website env may also be an MCP server, so an agent can act on a site through tools as well as its pages. Give a
+`WebsiteEnvironment` `@tool` (or `@resource`) methods, as an MCP env has; they need the `mcp` package. The site then
+serves them at `/mcp` (streamable HTTP) beside its pages, `@api` routes and data plane, and its card declares that
+endpoint as its `mcp` interface (`additionalInterfaces`) and lists the tools under `capabilities.tools`. A site without
+tools serves no `/mcp` and declares no interface; `serves_mcp()` says which a site is.
+
+```python
+@environment_card(name="shop")
+@website(domains=["shop.example"], static="dist")
+class Shop(WebsiteEnvironment):
+    @tool()
+    def place_order(self, item: str, ctx: ToolContext) -> str:
+        """Place an order for item, as the caller."""
+        ...
+```
+
+A tool runs in the site's process, so it changes what its pages show and what `data/get` returns, and it reads the
+universe's time (`self.now()`) as a page's request does. The gateway reads each site's card when it starts, and serves
+the tools of a site whose card declares an `mcp` interface as it does an MCP env's: listed to agents with the rest,
+called with the caller's role in `ToolContext`. The site's `/mcp` is one of the paths its card advertises, which its
+browsing route (`/website/<name>/`) never reaches. `python -m agentenv_protocol.website.conformance` checks a declared
+endpoint (`mcp`): it answers `initialize` and lists the tools the card does.
+
 ## Computer drivers
 
 A computer driver is what runs inside a computer an agent uses through screenshots and input. Write

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/README.md

@@ -462,6 +462,31 @@ print(env.ready, env.problems)                    # False ['shop: seeded']
   asked, or answers no `WebsiteReadiness`, is a problem itself. A card or child without `ready`, an MCP server's or an
   older site's, isn't counted, so an env with no site serving it is ready with no problems.
 
+## Websites with tools
+
+A website env may also be an MCP server, so an agent can act on a site through tools as well as its pages. Give a
+`WebsiteEnvironment` `@tool` (or `@resource`) methods, as an MCP env has; they need the `mcp` package. The site then
+serves them at `/mcp` (streamable HTTP) beside its pages, `@api` routes and data plane, and its card declares that
+endpoint as its `mcp` interface (`additionalInterfaces`) and lists the tools under `capabilities.tools`. A site without
+tools serves no `/mcp` and declares no interface; `serves_mcp()` says which a site is.
+
+```python
+@environment_card(name="shop")
+@website(domains=["shop.example"], static="dist")
+class Shop(WebsiteEnvironment):
+    @tool()
+    def place_order(self, item: str, ctx: ToolContext) -> str:
+        """Place an order for item, as the caller."""
+        ...
+```
+
+A tool runs in the site's process, so it changes what its pages show and what `data/get` returns, and it reads the
+universe's time (`self.now()`) as a page's request does. The gateway reads each site's card when it starts, and serves
+the tools of a site whose card declares an `mcp` interface as it does an MCP env's: listed to agents with the rest,
+called with the caller's role in `ToolContext`. The site's `/mcp` is one of the paths its card advertises, which its
+browsing route (`/website/<name>/`) never reaches. `python -m agentenv_protocol.website.conformance` checks a declared
+endpoint (`mcp`): it answers `initialize` and lists the tools the card does.
+
 ## Computer drivers
 
 A computer driver is what runs inside a computer an agent uses through screenshots and input. Write

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/examples/website/notes/README.md

@@ -22,9 +22,11 @@ them. The page shows the universe's time.
   sends `AgentEnv-Role: admin` with `AgentEnv-Role-Key` equal to the container's `WEBSITE_ROLE_KEY`; any other caller
   gets 403. The gateway passes on whatever role a browser sends, so without the key a page could claim `admin`; with no
   `WEBSITE_ROLE_KEY` set, every caller is `default` and the route is closed.
-- **Users.** `ApiContext.user` is the user in the signed session cookie. With no cookie, it is the acting user (the
-  data's `current_user`, which `acting_user()` returns), and `GET /api/session` signs that user in. `POST /api/sign-in` switches to another seeded
-  user. A user's notes are invisible to every other user, and another user's note answers 404.
+- **Users.** `ApiContext.user` is the user in the signed session cookie, `agentenv_session_notes` (the site's own, so
+  it doesn't collide with another site's under the same gateway host; the card names it). With no cookie, it is the
+  acting user (the data's `current_user`, which `acting_user()` returns), and `GET /api/session` signs that user in.
+  `POST /api/sign-in` switches to another seeded user. A user's notes are invisible to every other user, and another
+  user's note answers 404.
 - **State.** The site keeps its users and notes itself, starting from `data/seed.json`, and serves them through its
   data hooks: `data/add` adds a part's records by id (a data part, or a file part by bytes or `file://`), `data/get`
   exports them, and `data/reset` empties them. `data/get` is how agentenv reads what a task left the site with.
@@ -65,11 +67,13 @@ the test above runs this repo's.
 ```bash
 docker build -t notes-site .
 docker run -d --name notes-site -p 18080:8000 notes-site
-python -m agentenv_protocol.website.conformance http://localhost:18080 --clock-host host.docker.internal
+python -m agentenv_protocol.website.conformance http://localhost:18080 --clock-host host.docker.internal --strict
 curl -s http://localhost:18080/api/notes
 ```
 
-Use `--clock-host` so the container can reach the checker's clock. The clock check leaves the server following a
+Use `--clock-host` so the container can reach the checker's clock. `--strict` fails on a recommended check's warning
+too (the card, `X-Universe-Now`, the clock, forwarded headers, cookies); without it only the contract's required checks
+fail the run, and Notes passes every check either way. The clock check leaves the server following a
 clock that is gone once the check ends: later timestamps start from 2031 until the server is synced again, so restart
 the container before using it.
 

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/pyproject.toml

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

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/src/agentenv_protocol/website/conformance.py

@@ -1,13 +1,21 @@
-"""Check a running site's server against ``urn:agentenv:website/v1``, whatever it's written in:
-``python -m agentenv_protocol.website.conformance <url>`` prints each check and exits 1 when one failed (a warning
-doesn't), 2 when the server couldn't be reached. Everything goes over HTTP: the card, ``/`` under a made-up host, readiness by the card's
-``website/v1`` ``ready``, whose answer must be a ``WebsiteReadiness`` (by the declared health path, deprecated, for a
-card without it), ``X-Universe-Now`` on every answer the other checks got, a data-plane round trip at the card's ``url``
-(data/get, data/reset, data/get, which no longer returns the exported data, data/add of what the first data/get
-returned, data/get again), ``clock/v1``'s
-``sync_time`` against a clock the checker serves, and the forwarded headers wherever an answer shows them, on ``/`` and
-on a GET route with its trailing slash toggled, which a server may redirect, and the cookies those answers set:
-none tied to a domain, and a warning for one whose lifetime is an absolute ``Expires`` with no ``Max-Age``.
+"""Check a running site's server against ``urn:agentenv:website/v1``, whatever it's written in: ``python -m
+agentenv_protocol.website.conformance <url>`` prints each check and exits 1 when a required one failed (or, with
+``--strict``, when a recommended one warned), 2 when the server couldn't be reached. Everything goes over HTTP.
+
+The required checks are the contract, what agentenv, the gateway and a browser rely on of a website env's server: a
+card declaring the site's domains, readiness and routes; ``/`` serving HTML under a made-up host; the site ready, by
+the card's ``website/v1`` ``ready``, whose answer must be a ``WebsiteReadiness`` (by the declared health path,
+deprecated, for a card without it); the data plane's and card's paths not the site's pages; and the data plane the
+card advertises, whose round trip at the card's ``url`` (data/get, data/reset, data/get, which no longer returns the
+exported data, data/add of what the first data/get returned, data/get again) returns what it was given; and, for a
+card declaring an ``mcp`` interface, a site that is an MCP server too, that endpoint answering ``initialize`` and
+listing, every page of ``tools/list`` read, no tool its card doesn't (streamable HTTP, ``MCP_PROTOCOL_VERSION``); a
+card's tool it doesn't list is warned, since a hidden-by-default tool is listed to no caller until one enables it.
+A failed one is ``failed``. The recommended checks are what an SDK site does and the gateway uses when a server offers it:
+``X-Universe-Now`` on every answer the other checks got, ``clock/v1``'s ``sync_time`` against a clock the checker serves, the forwarded headers
+wherever an answer shows them (on ``/`` and on a GET route with its trailing slash toggled, which a server may
+redirect), and the cookies those answers set: none tied to a domain, the session path's the one the card names, and
+none whose lifetime is an absolute ``Expires`` with no ``Max-Age``. A failed one is ``warned``.
 
 Every request goes to the server under check: a card's path or URL naming another scheme, host or port fails the check
 that would have used it, with nothing sent there. The round trip leaves the server's data as it found it, adding the
@@ -33,25 +41,35 @@ import httpx
 from pydantic import ValidationError
 
 from ..client import find_extension, find_extension_method
-from ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH
+from ..types import MCP_TRANSPORT, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH
 from .clock import CLOCK_EXTENSION_URI, UNIVERSE_NOW_HEADER, iso, parse_time
 from .readiness import DEFAULT_HEALTH_PATH, WEBSITE_EXTENSION_URI, WEBSITE_READY_OP, WebsiteReadiness
 
 Status = Literal["passed", "failed", "skipped", "warned"]
 CLOCK_START = datetime.datetime(2031, 5, 6, 7, 8, 9, tzinfo=datetime.timezone.utc)
 CLOCK_SLACK_S = 120
+MCP_PROTOCOL_VERSION = "2025-06-18"
+MCP_LIST_PAGES = 100
 
 
 @dataclasses.dataclass(frozen=True)
 class Result:
+    """One check's outcome; ``required`` for a check of the contract, whose failure is ``failed``, and not for a
+    recommended one, whose failure is ``warned``."""
+
     name: str
     status: Status
     detail: str = ""
+    required: bool = True
 
     @property
     def passed(self) -> bool:
         return self.status != "failed"
 
+    def fails(self, strict: bool = False) -> bool:
+        """Whether the result fails the run: a failed check, or with ``strict`` a warned one too."""
+        return self.status == "failed" or (strict and self.status == "warned")
+
 
 def check(base_url: str, *, client: httpx.Client | None = None, clock_host: str = "127.0.0.1",
           timeout: float = 30) -> list[Result]:
@@ -92,19 +110,27 @@ class _Checker:
             card = response.json() if response.status_code == 200 else {}
         except ValueError:
             card = {}
+        card = card if isinstance(card, dict) else {}
         site = (find_extension(card, WEBSITE_EXTENSION_URI) or {}).get("params") or {}
         health = site.get("health") if isinstance(site.get("health"), str) else DEFAULT_HEALTH_PATH
-        steps = (("any_host", self._any_host), ("health", lambda: self._health(card, health)),
-                 ("universe_now", self._universe_now), ("data_plane", lambda: self._data_plane(card)),
-                 ("clock", lambda: self._clock(card)), ("forwarded", lambda: self._forwarded(site)),
-                 ("cookies", lambda: self._cookies(site)))
-        outcomes = {name: _outcome(step) for name, step in steps if name != "universe_now"}
+        # (name, required, check): a recommended check's failure is warned.
+        steps = (("card", True, lambda: self._card(response, card, site)), ("any_host", True, self._any_host),
+                 ("health", True, lambda: self._health(card, health)), ("universe_now", False, self._universe_now),
+                 ("reserved_paths", True, self._reserved_paths), ("data_plane", True, lambda: self._data_plane(card)),
+                 ("mcp", True, lambda: self._mcp(card)),
+                 ("clock", False, lambda: self._clock(card)), ("forwarded", False, lambda: self._forwarded(site)),
+                 ("cookies", False, lambda: self._cookies(site)))
+        outcomes = {name: _outcome(step) for name, _required, step in steps if name != "universe_now"}
         outcomes["universe_now"] = _outcome(self._universe_now)
-        return [self._card(response, card, site), *(Result(name, *outcomes[name]) for name, _step in steps)]
+        results = []
+        for name, required, _step in steps:
+            status, detail = outcomes[name]
+            results.append(Result(name, "warned" if status == "failed" and not required else status, detail, required))
+        return results
 
-    def _card(self, response: httpx.Response, card: dict, site: dict) -> Result:
+    def _card(self, response: httpx.Response, card: dict, site: dict) -> tuple[Status, str]:
         if response.status_code != 200:
-            return Result("card", "failed", f"{WELL_KNOWN_PATH} answered {response.status_code}")
+            return "failed", f"{WELL_KNOWN_PATH} answered {response.status_code}"
         problems = []
         if not site:
             problems.append(f"declares no {WEBSITE_EXTENSION_URI} with params")
@@ -117,7 +143,7 @@ class _Checker:
         if not isinstance(routes, list) or not all(isinstance(r, dict) and {"method", "path", "name"} <= set(r)
                                                    for r in routes):
             problems.append("its params' routes aren't a list of {method, path, name}")
-        return Result("card", "failed" if problems else "passed", "; ".join(problems))
+        return ("failed" if problems else "passed"), "; ".join(problems)
 
     def _any_host(self) -> tuple[Status, str]:
         host = f"conformance-{uuid.uuid4().hex[:8]}.invalid"
@@ -159,6 +185,15 @@ class _Checker:
             parse_time(response.headers[UNIVERSE_NOW_HEADER])
         return "passed", f"on all {len(self.responses)} answers"
 
+    def _reserved_paths(self) -> tuple[Status, str]:
+        paths = [RPC_PATH, WELL_KNOWN_PATH, f"{RPC_PATH}/conformance-{uuid.uuid4().hex[:8]}", f"{RPC_PATH}/",
+                 f"{WELL_KNOWN_PATH}/"]
+        for path in paths:
+            response = self.get(path)
+            if response.is_success and response.headers.get("content-type", "").startswith("text/html"):
+                return "failed", f"{path} answered a page, but the gateway keeps {RPC_PATH} and {WELL_KNOWN_PATH}"
+        return "passed", f"no page at {', '.join(paths)}"
+
     def _rpc(self, method: str, params: dict | None = None) -> dict:
         response = self._seen(self.client.post(self.rpc_url, json={"jsonrpc": "2.0", "id": method,
                                                                                "method": method, "params": params or {}}))
@@ -171,7 +206,8 @@ class _Checker:
 
     def _data_plane(self, card: dict) -> tuple[Status, str]:
         operations = (card.get("capabilities") or {}).get("operations")
-        missing = [m for m in (METHOD_GET, METHOD_RESET, METHOD_ADD) if operations is not None and m not in operations]
+        operations = operations if isinstance(operations, list) else []
+        missing = [m for m in (METHOD_GET, METHOD_RESET, METHOD_ADD) if m not in operations]
         if missing:
             return "failed", f"the card's operations lack {', '.join(missing)}"
         url = card.get("url")
@@ -198,6 +234,55 @@ class _Checker:
             return "failed", "data/get after data/reset and data/add of its own export returned other data"
         return "passed", f"{len(exported)} part(s) round-tripped through reset and add"
 
+    def _mcp(self, card: dict) -> tuple[Status, str]:
+        """The MCP endpoint the card declares answers ``initialize`` and lists no tool the card doesn't, reading up to
+        ``MCP_LIST_PAGES`` pages of ``tools/list``; its answers needn't carry ``X-Universe-Now``, which the MCP
+        transport doesn't promise."""
+        interfaces = [i for i in card.get("additionalInterfaces") or [] if isinstance(i, dict)
+                      and i.get("transport") == MCP_TRANSPORT]
+        if not interfaces:
+            return "skipped", "the card declares no mcp interface"
+        path = interfaces[0].get("url")
+        if not isinstance(path, str) or not path:
+            return "failed", f"the card's mcp interface has no url: {path!r}"
+        url = self._url(path)
+        headers = {"Accept": "application/json, text/event-stream"}
+        first = self.client.post(url, headers=headers, json={
+            "jsonrpc": "2.0", "id": "initialize", "method": "initialize",
+            "params": {"protocolVersion": MCP_PROTOCOL_VERSION, "capabilities": {},
+                       "clientInfo": {"name": "agentenv-website-conformance", "version": "1"}}})
+        server = _mcp_result(first, "initialize", "initialize").get("serverInfo") or {}
+        if session := first.headers.get("mcp-session-id"):
+            headers["Mcp-Session-Id"] = session
+        try:
+            self.client.post(url, headers=headers, json={"jsonrpc": "2.0", "method": "notifications/initialized"})
+            served: list = []
+            cursor = None
+            for _page in range(MCP_LIST_PAGES):
+                listed = _mcp_result(self.client.post(url, headers=headers, json={
+                    "jsonrpc": "2.0", "id": "tools/list", "method": "tools/list",
+                    **({"params": {"cursor": cursor}} if cursor else {})}), "tools/list", "tools/list")
+                if not isinstance(listed, dict) or not isinstance(listed.get("tools"), list):
+                    return "failed", f"tools/list at {path} answered no tools list: {str(listed)[:200]}"
+                served += [t.get("name") for t in listed["tools"] if isinstance(t, dict)]
+                cursor = listed.get("nextCursor")
+                if not cursor:
+                    break
+            else:
+                return "failed", f"tools/list at {path} still had a next page after {MCP_LIST_PAGES}"
+        finally:
+            if session:
+                with contextlib.suppress(httpx.HTTPError):
+                    self.client.delete(url, headers=headers)
+        advertised = {t.get("name") for t in (card.get("capabilities") or {}).get("tools") or [] if isinstance(t, dict)}
+        if unadvertised := sorted(set(served) - advertised):
+            return "failed", f"tools/list at {path} named {unadvertised}, which the card doesn't list"
+        name = server.get("name") or "the server"
+        if unlisted := sorted(advertised - set(served)):
+            return "warned", (f"{name} at {path} lists {len(served)} of the card's tools, not {unlisted}: hidden by "
+                              "default, or missing")
+        return "passed", f"{name} at {path} lists the card's {len(served)} tool(s)"
+
     def _clock(self, card: dict) -> tuple[Status, str]:
         if find_extension(card, CLOCK_EXTENSION_URI) is None:
             return "failed", f"the card declares no {CLOCK_EXTENSION_URI}"
@@ -238,14 +323,19 @@ class _Checker:
         return "passed", f"no answer to {', '.join(paths)} named the internal Host"
 
     def _cookies(self, site: dict) -> tuple[Status, str]:
+        session = []
         if isinstance(site.get("session_path"), str):
-            self.get(site["session_path"])
+            session = self.get(site["session_path"]).headers.get_list("set-cookie")
         cookies = [c for r in self.responses for c in r.headers.get_list("set-cookie")]
         if not cookies:
             return "skipped", "no answer set a cookie"
         scoped = sorted({c.split("=", 1)[0] for c in cookies if "domain" in _attributes(c)})
         if scoped:
             return "failed", f"cookies tied to a domain: {', '.join(scoped)}"
+        named = site.get("session_cookie")
+        if isinstance(named, str) and session and named not in {c.split("=", 1)[0].strip() for c in session}:
+            return "failed", (f"{site['session_path']} set {', '.join(c.split('=', 1)[0] for c in session)}, not the "
+                              f"card's {named}")
         absolute = sorted({c.split("=", 1)[0] for c in cookies if "expires" in _attributes(c) and "max-age" not in _attributes(c)})
         if absolute:
             return "warned", (f"cookies with an absolute Expires and no Max-Age, which a browser on another clock "
@@ -275,6 +365,48 @@ def _outcome(step: Callable[[], tuple[Status, str]]) -> tuple[Status, str]:
         return "failed", f"{type(e).__name__}: {e}"
 
 
+def _mcp_result(response: httpx.Response, method: str, request_id: str) -> dict:
+    """The result of the JSON-RPC reply to request ``request_id``: the answer's JSON, or the reply among an event
+    stream's messages, each event's data lines joined, as ``ToolSession`` reads them."""
+    if response.headers.get("content-type", "").startswith("text/event-stream"):
+        messages = []
+        for data in _sse_data(response.text):
+            try:
+                messages.append(json.loads(data))
+            except ValueError:
+                raise RuntimeError(f"{method} answered an event that isn't JSON: {data[:200]!r}") from None
+    else:
+        try:
+            messages = [json.loads(response.text)]
+        except ValueError:
+            raise RuntimeError(f"{method} answered {response.status_code} with no JSON-RPC answer: "
+                               f"{response.text[:200]!r}") from None
+    body = next((m for m in messages if isinstance(m, dict) and m.get("id") == request_id
+                 and ("result" in m or "error" in m)), None)
+    if body is None or "result" not in body:
+        raise RuntimeError(f"{method} answered {response.status_code}: {str(body or messages)[:200]}")
+    return body["result"] or {}
+
+
+def _sse_data(text: str) -> Iterator[str]:
+    """The data of each ``message`` event in a server-sent event stream, its data lines joined; an event the stream
+    ends inside is dropped, as are events with no data."""
+    event, data = "message", []
+    for line in text.splitlines():
+        if not line:
+            payload = "\n".join(data)
+            if payload.strip() and event == "message":
+                yield payload
+            event, data = "message", []
+            continue
+        field, _, value = line.partition(":")
+        value = value[1:] if value.startswith(" ") else value
+        if field == "data":
+            data.append(value)
+        elif field == "event":
+            event = value
+
+
 def _field_error(error: dict) -> str:
     """One of a ``ValidationError``'s errors as a person reads it: where, then what."""
     where = ".".join(map(str, error.get("loc") or ())) or "the answer"
@@ -341,6 +473,7 @@ def main(argv: list[str] | None = None) -> int:
     parser.add_argument("url", help="where the server answers, such as http://localhost:8000")
     parser.add_argument("--clock-host", default="127.0.0.1", help="the address the server reaches this checker at")
     parser.add_argument("--timeout", type=float, default=30, help="seconds for each request")
+    parser.add_argument("--strict", action="store_true", help="fail on a recommended check's warning too")
     args = parser.parse_args(argv)
     try:
         results = check(args.url, clock_host=args.clock_host, timeout=args.timeout)
@@ -348,10 +481,12 @@ def main(argv: list[str] | None = None) -> int:
         print(f"couldn't reach {args.url}: {type(e).__name__}: {e}", file=sys.stderr)
         return 2
     for result in results:
-        print(f"{_MARK[result.status]} {result.name}{': ' + result.detail if result.detail else ''}")
-    failed = sum(not r.passed for r in results)
-    print(f"{args.url}: {len(results) - failed} passed, warned or skipped, {failed} failed")
-    return 1 if failed else 0
+        kind = "required" if result.required else "recommended"
+        print(f"{_MARK[result.status]} {result.name} ({kind}){': ' + result.detail if result.detail else ''}")
+    counts = {status: sum(r.status == status for r in results) for status in _MARK}
+    print(f"{args.url}: {counts['passed']} passed, {counts['failed']} failed, {counts['warned']} warned, "
+          f"{counts['skipped']} skipped{' (strict)' if args.strict else ''}")
+    return 1 if any(r.fails(args.strict) for r in results) else 0
 
 
 if __name__ == "__main__":

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/src/agentenv_protocol/website/environment.py

@@ -8,6 +8,10 @@ usually its schema of the env's database (``database_url``), and serves it throu
 (``@reset_data``, ``@add_data``, ``@get_data``) as any AgentEnvEnvironment does: ``data/get`` is how agentenv reads
 what a task left a site with.
 
+A site may also be an MCP server, as an MCP env is: its ``@tool`` and ``@resource`` methods are served at ``/mcp``
+(streamable HTTP, of the ``mcp`` package), which its card declares as its ``mcp`` interface and lists the tools of, so
+an agent can act on the site through tools beside its pages. A site with none serves no ``/mcp``.
+
 One route is built in, replaced by a site's own ``@api`` route at its very path and answering before one whose path
 parameters would also match it: ``/api/session``, which a frontend calls to learn who is signed in, signing the acting
 user in when nobody is (GET), or to sign out (DELETE)."""
@@ -32,9 +36,12 @@ from starlette.routing import Route
 
 from ..agent_env_environment import (
     AgentEnvEnvironment,
+    _RESOURCE_ATTR,
+    _TOOL_ATTR,
     AgentEnvStarletteApplication,
     _marked_members,
     _maybe_await,
+    create_fastmcp_app,
     extension,
 )
 from .clock import CLOCK_EXTENSION_URI, UNIVERSE_NOW_HEADER, ClockUnavailable, UniverseClock, clock_patch_script, iso
@@ -42,7 +49,7 @@ from .errors import ApiError, NotFound
 from .readiness import SITE_READY_TIMEOUT_S, WEBSITE_EXTENSION_URI, WEBSITE_READY_OP, WebsiteReadiness
 from .routes import (ApiContext, ApiRoute, endpoint, error_response, forwarded_prefix, openapi, openapi_path, request_role,
                      reserved_path, routes_of)
-from .session import SESSION_COOKIE, SessionSigner
+from .session import SessionSigner, session_cookie_name
 
 SESSION_PATH = "/api/session"
 CHECK_TIMEOUT_S = 10.0
@@ -114,7 +121,7 @@ class WebsiteEnvironment(AgentEnvEnvironment):
 
     def __init__(self) -> None:
         self.clock = UniverseClock()
-        self._signer = SessionSigner()
+        self._signer = SessionSigner(cookie_name=session_cookie_name(self._build_card().name))
         self._started = time.monotonic()
         self._checking: dict[str, asyncio.Future] = {}
 
@@ -126,6 +133,11 @@ class WebsiteEnvironment(AgentEnvEnvironment):
     def routes(cls) -> list[ApiRoute]:
         return routes_of(cls)
 
+    @property
+    def session_cookie(self) -> str:
+        """The name of the site's session cookie, ``agentenv_session_<environment_name>``."""
+        return self._session_signer().cookie_name
+
     @property
     def database_url(self) -> str | None:
         """Where the site keeps its task state: its own schema of the env's database."""
@@ -148,7 +160,7 @@ class WebsiteEnvironment(AgentEnvEnvironment):
 
     def context(self, request: Request) -> ApiContext:
         """The ``ApiContext`` of ``request``, for a mounted ``app``'s routes as for ``@api`` ones."""
-        session = self._session_signer().decode(request.cookies.get(SESSION_COOKIE))
+        session = self._session_signer().read(request.cookies)
         user = session["user"] if session is not None else self.acting_user()
         return ApiContext(request, user, request_role(request), session, self._session_signer())
 
@@ -159,8 +171,15 @@ class WebsiteEnvironment(AgentEnvEnvironment):
         api_routes = self.routes()
         taken = {openapi_path(r.path) for r in api_routes}
         root = self._site_path(declaration.static) if declaration.static is not None else None
-        asgi = Starlette(middleware=[Middleware(_Forwarded), Middleware(_Universe, env=self)])
-        AgentEnvStarletteApplication(self._build_card(), self).add_routes_to_app(asgi)
+        middleware = [Middleware(_Forwarded), Middleware(_Universe, env=self)]
+        if self.serves_mcp():
+            self.mcp = create_fastmcp_app(self, card=self._build_card())
+            served = self.mcp.streamable_http_app()
+            asgi = Starlette(middleware=middleware, lifespan=served.router.lifespan_context)
+            asgi.router.routes.extend(served.routes)
+        else:
+            asgi = Starlette(middleware=middleware)
+            AgentEnvStarletteApplication(self._build_card(), self).add_routes_to_app(asgi)
         if SESSION_PATH not in taken:
             asgi.router.routes.append(Route(SESSION_PATH, self._session, methods=["GET", "DELETE"]))
         asgi.router.routes.extend(Route(r.path, _unreserved(endpoint(getattr(self, r.fn.__name__), r, self.context)),
@@ -170,6 +189,11 @@ class WebsiteEnvironment(AgentEnvEnvironment):
         self._mounted = True
         return asgi
 
+    def serves_mcp(self) -> bool:
+        """Whether the site is an MCP server too: it has ``@tool`` or ``@resource`` methods, or forwards tools."""
+        return any(True for _ in _marked_members(self, _TOOL_ATTR)) or any(
+            True for _ in _marked_members(self, _RESOURCE_ATTR)) or bool(self.forwarded_tools())
+
     def mount(self, app: Any) -> Any:
         raise TypeError(f"{type(self).__name__} builds its own app with create_app(); set app = ... to serve more")
 
@@ -186,7 +210,7 @@ class WebsiteEnvironment(AgentEnvEnvironment):
         if uri == WEBSITE_EXTENSION_URI:
             declaration = self.declaration()
             return {"domains": list(declaration.domains),
-                    "routes": [r.advertised() for r in self.routes()], "session_cookie": SESSION_COOKIE,
+                    "routes": [r.advertised() for r in self.routes()], "session_cookie": self.session_cookie,
                     "session_path": SESSION_PATH}
         return super().extension_params(uri)
 

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/src/agentenv_protocol/website/routes.py

@@ -28,7 +28,7 @@ from ..agent_env_environment import _coerce_scalar, _maybe_await, _schema_for_an
 from ..tool_context import DEFAULT_ROLE, caller_from_request
 from ..types import RPC_PATH, WELL_KNOWN_PATH
 from .errors import ApiError, BadRequest, Forbidden
-from .session import SESSION_COOKIE, SESSION_TTL_S, SessionSigner
+from .session import SESSION_TTL_S, SessionSigner
 
 logger = logging.getLogger(__name__)
 
@@ -154,7 +154,8 @@ class ApiContext:
 
     def apply(self, response: Response) -> Response:
         for value in self._set_cookie:
-            response.set_cookie(SESSION_COOKIE, value, max_age=SESSION_TTL_S, path="/", httponly=True, samesite="lax")
+            response.set_cookie(self._signer.cookie_name, value, max_age=SESSION_TTL_S, path="/", httponly=True,
+                                samesite="lax")
         return response
 
 

{agentenv_framework_protocol-0.1.468 → agentenv_framework_protocol-0.1.469}/src/agentenv_protocol/website/session.py

@@ -2,7 +2,8 @@
 under ``WEBSITE_SESSION_SECRET``, which a deploy sets for each site so its sessions outlive its process, or a secret
 of the process's own when that isn't set. The cookie names no domain, so it holds under whatever host the site is
 reached at, and its lifetime is a ``Max-Age``, never an absolute ``Expires``, so the browser's clock and the site's
-needn't agree."""
+needn't agree. Its name is the site's own, ``agentenv_session_<name>``, so two sites a browser reaches under one gateway
+host (``/website/a/``, ``/website/b/``) keep a session each."""
 from __future__ import annotations
 
 import base64
@@ -11,6 +12,7 @@ import hashlib
 import hmac
 import json
 import os
+import re
 import secrets
 import time
 
@@ -18,12 +20,30 @@ SESSION_COOKIE = "agentenv_session"
 SESSION_SECRET_ENV = "WEBSITE_SESSION_SECRET"
 SESSION_TTL_S = 7 * 24 * 3600
 SECRET_BYTES = 32
+_NOT_TOKEN = re.compile(r"[^A-Za-z0-9_.-]")
+
+
+def _cookie_suffix(environment_name: str) -> str:
+    """The part of a site's cookie names that is its own: the name itself when a cookie name can hold each of its
+    characters, else the name with each such character made ``_`` and ``~`` and a hash of the whole name appended. No
+    name kept as itself holds a ``~``, so two distinct names never make one suffix."""
+    if not _NOT_TOKEN.search(environment_name):
+        return environment_name
+    digest = hashlib.sha256(environment_name.encode("utf-8", "surrogatepass")).hexdigest()[:12]
+    return f"{_NOT_TOKEN.sub('_', environment_name)}~{digest}"
+
+
+def session_cookie_name(environment_name: str | None) -> str:
+    """The session cookie of the site named ``environment_name``: ``agentenv_session_<name>``, a name a cookie name
+    can't hold spelled as ``_cookie_suffix`` spells it; the shared ``agentenv_session`` for a site with no name."""
+    return f"{SESSION_COOKIE}_{_cookie_suffix(environment_name)}" if environment_name else SESSION_COOKIE
 
 
 class SessionSigner:
-    def __init__(self, secret: str | bytes | None = None) -> None:
+    def __init__(self, secret: str | bytes | None = None, cookie_name: str = SESSION_COOKIE) -> None:
         secret = secret if secret is not None else os.environ.get(SESSION_SECRET_ENV)
         self._key = (secret.encode() if isinstance(secret, str) else secret) or secrets.token_bytes(SECRET_BYTES)
+        self.cookie_name = cookie_name
 
     def encode(self, user: str | None, ttl_s: int = SESSION_TTL_S) -> str:
         """The cookie value for ``user`` signed in, or signed out when None, good for ``ttl_s`` seconds."""
@@ -45,10 +65,14 @@ class SessionSigner:
             return None
         return {"user": data.get("u")}
 
+    def read(self, cookies: dict) -> dict | None:
+        """The session of a request's ``cookies``, from the site's own cookie."""
+        return self.decode(cookies.get(self.cookie_name))
+
     def cookie(self, user: str | None, ttl_s: int = SESSION_TTL_S) -> dict:
         """The cookie a browser adds to be signed in as ``user``, in browser/v1's shape with ``max_age`` for its
         lifetime; its domain is left to whoever adds it."""
-        return {"name": SESSION_COOKIE, "value": self.encode(user, ttl_s), "path": "/", "max_age": ttl_s,
+        return {"name": self.cookie_name, "value": self.encode(user, ttl_s), "path": "/", "max_age": ttl_s,
                 "httpOnly": True, "sameSite": "Lax"}
 
     def _sign(self, payload: str) -> str: