agentenv-framework-protocol 0.1.331__tar.gz → 0.1.332__tar.gz

{agentenv_framework_protocol-0.1.331 → agentenv_framework_protocol-0.1.332}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.331
+Version: 0.1.332
 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
@@ -245,7 +245,48 @@ class SlackEnv(AgentEnvEnvironment):
         return [DataPart(data=self.state())]
 ```
 
-Dependencies are intentionally light (`pydantic`, `starlette`) so the package can be added to environment server images without pulling a heavier framework — `mcp` is imported lazily inside `create_fastmcp_app()` and is deliberately not a dependency.
+Dependencies are intentionally light (`pydantic`, `starlette`, `httpx`) so the package can be added to environment server images without pulling a heavier framework — `mcp` is imported lazily inside `create_fastmcp_app()` and is deliberately not a dependency.
+
+## Calling an env's tools
+
+A loop of your own, such as a trainer's rollout or an eval harness, reaches an env's tools through `ToolSession`. It
+is an MCP client for the env's streamable-HTTP endpoint, written on `httpx`, so it works wherever this package
+installs, whichever `mcp` version the loop's own environment pins.
+
+```python
+from agentenv_protocol import ToolSession
+
+async with ToolSession(mcp_url=mcp_url, role="alice@example.com") as session:
+    tools = await session.list_tools()                 # EnvironmentTool: name, description, inputSchema
+    result = await session.call_tool("slack_send_message", {"channel": "general", "text": "hi"})
+    print(result.text, result.isError)
+```
+
+- **The URL:** `mcp_url` is `DeployedEnv.mcp_url` in agent-env, or the address a card was fetched from joined with
+  `client.mcp_path(card)`.
+- **Sessions:** a `ToolSession` is one MCP session, and calls on it may run concurrently. `async with` opens and ends
+  it; `open()` and `close()` do the same for a session held across calls. A tool tells sessions apart by
+  `ctx.caller.session`: the session's id when the server is reached directly, or, behind a gateway, a key the gateway
+  gives each session. A session belongs to the event loop that opened it, and using or closing it on another raises
+  `RuntimeError`, so a caller with a synchronous API runs all of a session's calls on one loop of its own.
+- **Roles:** `role` is sent as `AgentEnv-Role` (`ROLE_HEADER`) and says who the caller is. A gateway lists only the
+  tools that role may use, answers a call to a hidden one with an error result, and forwards the role to the servers
+  behind it; a server reached directly reads the header itself. Either way a tool reads it as `ctx.caller.role`
+  ([Who is calling](#who-is-calling)), where `default`, like no role, is `None`. `headers` adds any others.
+- **Errors:**
+  - A tool that fails, or a call the server refuses (a tool hidden from the role, or an `on_tool_call` refusal),
+    returns a result with `isError` set and the server's text.
+  - `ToolSessionError` means the request failed at the MCP level: a JSON-RPC error, an HTTP error status, a reply
+    that can't be read, or a session the server no longer knows. After a restart, the env's state is usually gone too.
+    Only the server the session talks to reports this: a gateway reconnects to a child that restarted and retries the
+    call, and a stateless server has no session to lose, so neither restart raises anything.
+  - `httpx.TransportError` means the connection failed, and `TimeoutError` that a request outlived `timeout`
+    (600 s by default, the gateway's own limit on a tool call).
+  - `ToolSession` retries nothing. A call that raised may still have run on the server, or may yet run: a request
+    stalled on a bad link can arrive after the client has given up. So after any failed call the env's state is
+    unknown; read it back (`data/get`) or end the episode.
+- **Tools:** `list_tools()` returns the tools the role may use as `EnvironmentTool`, the type a card's
+  `capabilities.tools` holds. Each `inputSchema` is the JSON Schema a model API takes as the tool's parameters.
 
 ## A2A agent framework
 

{agentenv_framework_protocol-0.1.331 → agentenv_framework_protocol-0.1.332}/README.md

@@ -200,7 +200,48 @@ class SlackEnv(AgentEnvEnvironment):
         return [DataPart(data=self.state())]
 ```
 
-Dependencies are intentionally light (`pydantic`, `starlette`) so the package can be added to environment server images without pulling a heavier framework — `mcp` is imported lazily inside `create_fastmcp_app()` and is deliberately not a dependency.
+Dependencies are intentionally light (`pydantic`, `starlette`, `httpx`) so the package can be added to environment server images without pulling a heavier framework — `mcp` is imported lazily inside `create_fastmcp_app()` and is deliberately not a dependency.
+
+## Calling an env's tools
+
+A loop of your own, such as a trainer's rollout or an eval harness, reaches an env's tools through `ToolSession`. It
+is an MCP client for the env's streamable-HTTP endpoint, written on `httpx`, so it works wherever this package
+installs, whichever `mcp` version the loop's own environment pins.
+
+```python
+from agentenv_protocol import ToolSession
+
+async with ToolSession(mcp_url=mcp_url, role="alice@example.com") as session:
+    tools = await session.list_tools()                 # EnvironmentTool: name, description, inputSchema
+    result = await session.call_tool("slack_send_message", {"channel": "general", "text": "hi"})
+    print(result.text, result.isError)
+```
+
+- **The URL:** `mcp_url` is `DeployedEnv.mcp_url` in agent-env, or the address a card was fetched from joined with
+  `client.mcp_path(card)`.
+- **Sessions:** a `ToolSession` is one MCP session, and calls on it may run concurrently. `async with` opens and ends
+  it; `open()` and `close()` do the same for a session held across calls. A tool tells sessions apart by
+  `ctx.caller.session`: the session's id when the server is reached directly, or, behind a gateway, a key the gateway
+  gives each session. A session belongs to the event loop that opened it, and using or closing it on another raises
+  `RuntimeError`, so a caller with a synchronous API runs all of a session's calls on one loop of its own.
+- **Roles:** `role` is sent as `AgentEnv-Role` (`ROLE_HEADER`) and says who the caller is. A gateway lists only the
+  tools that role may use, answers a call to a hidden one with an error result, and forwards the role to the servers
+  behind it; a server reached directly reads the header itself. Either way a tool reads it as `ctx.caller.role`
+  ([Who is calling](#who-is-calling)), where `default`, like no role, is `None`. `headers` adds any others.
+- **Errors:**
+  - A tool that fails, or a call the server refuses (a tool hidden from the role, or an `on_tool_call` refusal),
+    returns a result with `isError` set and the server's text.
+  - `ToolSessionError` means the request failed at the MCP level: a JSON-RPC error, an HTTP error status, a reply
+    that can't be read, or a session the server no longer knows. After a restart, the env's state is usually gone too.
+    Only the server the session talks to reports this: a gateway reconnects to a child that restarted and retries the
+    call, and a stateless server has no session to lose, so neither restart raises anything.
+  - `httpx.TransportError` means the connection failed, and `TimeoutError` that a request outlived `timeout`
+    (600 s by default, the gateway's own limit on a tool call).
+  - `ToolSession` retries nothing. A call that raised may still have run on the server, or may yet run: a request
+    stalled on a bad link can arrive after the client has given up. So after any failed call the env's state is
+    unknown; read it back (`data/get`) or end the episode.
+- **Tools:** `list_tools()` returns the tools the role may use as `EnvironmentTool`, the type a card's
+  `capabilities.tools` holds. Each `inputSchema` is the JSON Schema a model API takes as the tool's parameters.
 
 ## A2A agent framework
 

{agentenv_framework_protocol-0.1.331 → agentenv_framework_protocol-0.1.332}/pyproject.toml

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

{agentenv_framework_protocol-0.1.331 → agentenv_framework_protocol-0.1.332}/src/agentenv_protocol/__init__.py

@@ -2,6 +2,7 @@
 
 from . import client
 from .preflight import intake_fit_check
+from .tool_client import ToolResult, ToolSession, ToolSessionError
 from .agent_env_environment import (
     AgentEnvApplication,
     AgentEnvEnvironment,
@@ -116,6 +117,9 @@ __all__ = [
     "uploaded_object_path",
     "MCP_PATH",
     "MCP_TRANSPORT",
+    "ToolSession",
+    "ToolResult",
+    "ToolSessionError",
     "MANIFEST_VERSION",
     "INTERFACE_MANIFEST_PATH",
     "GET_INTERFACES_EXTENSION_URI",

agentenv_framework_protocol-0.1.332/src/agentenv_protocol/tool_client.py

@@ -0,0 +1,205 @@
+"""MCP client for an environment's tools, over the streamable-HTTP transport on httpx alone: a trainer's or eval
+harness's own loop lists and calls an env's tools with it, whatever `mcp` version that loop's environment pins."""
+
+from __future__ import annotations
+
+import asyncio
+import contextlib
+import itertools
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, Field, field_validator
+
+from .tool_context import ROLE_HEADER
+from .types import PROTOCOL_VERSION, EnvironmentTool
+
+_MCP_PROTOCOL_VERSION = "2025-11-25"
+_SESSION_HEADER = "Mcp-Session-Id"
+_VERSION_HEADER = "MCP-Protocol-Version"
+_ACCEPT = "application/json, text/event-stream"
+_CLOSE_TIMEOUT_S = 5.0
+
+
+class ToolSessionError(RuntimeError):
+    """An MCP-level failure: a JSON-RPC error, an HTTP error status, a reply that can't be read, or a session the server
+    no longer knows. A tool that fails is not one; its result carries ``isError``."""
+
+
+class ToolResult(BaseModel):
+    content: list[dict] = Field(default_factory=list)
+    isError: bool = False
+
+    @field_validator("content")
+    @classmethod
+    def _text_blocks_carry_text(cls, content: list[dict]) -> list[dict]:
+        if any(block.get("type") == "text" and not isinstance(block.get("text"), str) for block in content):
+            raise ValueError("a text block has no string text")
+        return content
+
+    @property
+    def text(self) -> str:
+        return "\n".join(block["text"] for block in self.content if block.get("type") == "text")
+
+
+class ToolSession:
+    """One MCP session on an env's ``mcp_url``. Use it on the event loop that opened it, and after any failed call treat
+    the env's state as unknown: nothing is retried, and a call that raised may still run on the server."""
+
+    def __init__(self, *, mcp_url: str, role: str | None = None, headers: dict[str, str] | None = None,
+                 timeout: float = 600.0) -> None:
+        self.mcp_url = mcp_url
+        self.timeout = timeout
+        self.session_id: str | None = None
+        self.protocol_version: str | None = None
+        self._headers = {**(headers or {}), **({ROLE_HEADER: role} if role else {}), "Accept": _ACCEPT}
+        self._client: httpx.AsyncClient | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._ids = itertools.count(1)
+
+    async def __aenter__(self) -> ToolSession:
+        return await self.open()
+
+    async def __aexit__(self, *exc_info: object) -> None:
+        await self.close()
+
+    async def open(self) -> ToolSession:
+        """Start a new MCP session, ending the one this object holds, if any."""
+        await self.close()
+        self.session_id = self.protocol_version = None
+        self._loop = asyncio.get_running_loop()
+        self._client = httpx.AsyncClient(headers=self._headers, timeout=None, follow_redirects=True)
+        try:
+            result = await self._request("initialize", {
+                "protocolVersion": _MCP_PROTOCOL_VERSION,
+                "capabilities": {},
+                "clientInfo": {"name": "agentenv-protocol", "version": PROTOCOL_VERSION},
+            })
+            self.protocol_version = result.get("protocolVersion") or _MCP_PROTOCOL_VERSION
+            await self._deadline("notifications/initialized",
+                                 self._exchange({"jsonrpc": "2.0", "method": "notifications/initialized"}))
+        except BaseException:
+            await self.close()
+            raise
+        return self
+
+    async def close(self) -> None:
+        """End the session on the server, waiting at most 5 s (or ``timeout``, if shorter), then close the connection; a
+        server that is already gone is not an error."""
+        if self._client is None:
+            return
+        client, self._client = self._open_client(), None
+        try:
+            if self.session_id:
+                with contextlib.suppress(httpx.HTTPError, asyncio.TimeoutError):
+                    await asyncio.wait_for(client.delete(self.mcp_url, headers=self._session_headers()),
+                                           min(self.timeout, _CLOSE_TIMEOUT_S))
+        finally:
+            await client.aclose()
+
+    async def list_tools(self) -> list[EnvironmentTool]:
+        tools: list[EnvironmentTool] = []
+        params: dict[str, Any] = {}
+        while True:
+            result = await self._request("tools/list", params)
+            if not isinstance(result.get("tools"), list):
+                raise ToolSessionError("tools/list: unreadable result: tools is not a list")
+            tools += [_validated(EnvironmentTool, tool, "tools/list") for tool in result["tools"]]
+            if not result.get("nextCursor"):
+                return tools
+            params = {"cursor": result["nextCursor"]}
+
+    async def call_tool(self, name: str, arguments: dict[str, Any] | None = None) -> ToolResult:
+        result = await self._request("tools/call", {"name": name, "arguments": arguments or {}})
+        return _validated(ToolResult, result, "tools/call")
+
+    async def _request(self, method: str, params: dict[str, Any]) -> dict:
+        message = {"jsonrpc": "2.0", "id": next(self._ids), "method": method, "params": params}
+        reply = await self._deadline(method, self._exchange(message))
+        if "error" in reply:
+            error = reply["error"] if isinstance(reply["error"], dict) else {"message": reply["error"]}
+            raise ToolSessionError(f"{method} failed: {error.get('message')} (code {error.get('code')})")
+        if not isinstance(reply.get("result"), dict):
+            raise ToolSessionError(f"{method}: the reply has no result object")
+        return reply["result"]
+
+    async def _deadline(self, method: str, exchange: Any) -> Any:
+        try:
+            return await asyncio.wait_for(exchange, self.timeout)
+        except asyncio.TimeoutError as e:
+            raise TimeoutError(f"{method} did not finish within {self.timeout}s") from e
+
+    async def _exchange(self, message: dict) -> dict:
+        async with self._open_client().stream("POST", self.mcp_url, json=message,
+                                              headers=self._session_headers()) as response:
+            await self._raise_for_status(response, message["method"])
+            if "id" not in message:
+                return {}
+            if message["method"] == "initialize":
+                self.session_id = response.headers.get(_SESSION_HEADER)
+            content_type = response.headers.get("content-type", "")
+            try:
+                if content_type.startswith("text/event-stream"):
+                    async for data in _sse_data(response):
+                        reply = json.loads(data)
+                        if isinstance(reply, dict) and reply.get("id") == message["id"] and (
+                                "result" in reply or "error" in reply):
+                            return reply
+                    raise ToolSessionError(f"{message['method']}: the event stream ended before the reply")
+                if content_type.startswith("application/json"):
+                    reply = json.loads(await response.aread())
+                    if isinstance(reply, dict):
+                        return reply
+                    raise ToolSessionError(f"{message['method']}: the reply is not a JSON-RPC object")
+            except ValueError as e:
+                raise ToolSessionError(f"{message['method']}: unreadable reply: {e}") from e
+            raise ToolSessionError(f"{message['method']}: unexpected content type {content_type!r}")
+
+    async def _raise_for_status(self, response: httpx.Response, method: str) -> None:
+        if response.status_code == 404 and self.session_id:
+            raise ToolSessionError(f"{method}: the server no longer knows session {self.session_id}; it restarted "
+                                   "or ended the session, and the env's state may be gone with it")
+        if response.status_code >= 400:
+            body = (await response.aread()).decode(errors="replace")[:1000]
+            raise ToolSessionError(f"{method}: HTTP {response.status_code} from {self.mcp_url}: {body}")
+
+    def _session_headers(self) -> dict[str, str]:
+        headers = {_SESSION_HEADER: self.session_id} if self.session_id else {}
+        if self.protocol_version:
+            headers[_VERSION_HEADER] = self.protocol_version
+        return headers
+
+    def _open_client(self) -> httpx.AsyncClient:
+        if self._client is None:
+            raise RuntimeError("the ToolSession is not open: use `async with ToolSession(...)` or `await open()`")
+        if asyncio.get_running_loop() is not self._loop:
+            raise RuntimeError("the ToolSession was opened on another event loop; use and close it on that one")
+        return self._client
+
+
+def _validated(model: type[BaseModel], data: Any, method: str) -> Any:
+    try:
+        return model.model_validate(data)
+    except ValueError as e:
+        raise ToolSessionError(f"{method}: unreadable result: {e}") from e
+
+
+async def _sse_data(response: httpx.Response) -> AsyncIterator[str]:
+    """The data of each ``message`` event in a server-sent event stream; an event the stream ends inside is dropped,
+    as the SSE spec has it, and so are events with no data, such as a resumable server's priming event."""
+    event, data = "message", []
+    async for line in response.aiter_lines():
+        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

agentenv_framework_protocol-0.1.332/tests/test_tool_client.py

@@ -0,0 +1,385 @@
+"""ToolSession against a real AgentEnv FastMCP server in each streamable-HTTP mode, and against a scripted server for
+the wire cases a real one rarely produces: paged lists, busy event streams, lost sessions and broken replies."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import time
+from typing import Annotated
+
+import httpx
+import pytest
+from pydantic import Field
+
+from agentenv_protocol import (
+    ROLE_HEADER,
+    EnvironmentCard,
+    ToolContext,
+    ToolResult,
+    ToolSession,
+    ToolSessionError,
+    create_fastmcp_app,
+    tool,
+)
+
+_URL = "http://env/mcp"
+
+
+class _Items:
+    def __init__(self) -> None:
+        self.items: list[str] = []
+
+    @tool(name="{environment_name}_add_item")
+    async def add_item(self, item: Annotated[str, Field(description="The item to add.")], times: int = 1) -> str:
+        """Add an item to the store."""
+        self.items.extend([item] * times)
+        return json.dumps({"count": len(self.items)})
+
+    @tool()
+    async def list_items(self) -> str:
+        """List the stored items."""
+        return json.dumps({"items": self.items})
+
+    @tool()
+    async def echo_after(self, value: str, seconds: float) -> str:
+        """Answer with value after a pause."""
+        await asyncio.sleep(seconds)
+        return value
+
+    @tool()
+    def explode(self) -> str:
+        """Always fails."""
+        raise RuntimeError("the tool blew up")
+
+    @tool()
+    def whoami(self, ctx: ToolContext) -> str:
+        """Who is calling."""
+        return json.dumps({"role": ctx.caller.role, "session": ctx.caller.session})
+
+
+def _route_clients_to(monkeypatch, transport: httpx.AsyncBaseTransport) -> None:
+    real = httpx.AsyncClient
+    monkeypatch.setattr(httpx, "AsyncClient", lambda **kwargs: real(transport=transport, **kwargs))
+
+
+@pytest.fixture
+def serve_items(monkeypatch):
+    """Serve an _Items env with create_fastmcp_app in the given mode, in process; yields the handler."""
+    pytest.importorskip("mcp.server.fastmcp")
+
+    async def serve(**fastmcp_kwargs):
+        handler = _Items()
+        app = create_fastmcp_app(handler, card=EnvironmentCard(name="items"), **fastmcp_kwargs).streamable_http_app()
+        _route_clients_to(monkeypatch, httpx.ASGITransport(app=app))
+        return handler, app.router.lifespan_context(app)
+    return serve
+
+
+class _Scripted:
+    """A streamable-HTTP MCP server whose answer to each method a test sets, recording every request it receives."""
+
+    def __init__(self) -> None:
+        self.requests: list[httpx.Request] = []
+        self.sessions = {"s-1"}
+        self.answers: dict = {"tools/list": {"tools": []}}
+
+    async def __call__(self, request: httpx.Request) -> httpx.Response:
+        self.requests.append(request)
+        session = request.headers.get("mcp-session-id")
+        if request.method == "DELETE":
+            self.sessions.discard(session)
+            return httpx.Response(200)
+        message = json.loads(request.content)
+        if session is not None and session not in self.sessions:
+            return httpx.Response(404, json={"jsonrpc": "2.0", "id": "server-error",
+                                             "error": {"code": -32600, "message": "Session not found"}})
+        if "id" not in message:
+            return httpx.Response(202)
+        answer = self.answers.get(message["method"])
+        if callable(answer):
+            return answer(message)
+        if message["method"] == "initialize":
+            return httpx.Response(200, headers={"mcp-session-id": "s-1"}, json=_reply(message, {
+                "protocolVersion": "2025-06-18", "capabilities": {"tools": {}}, "serverInfo": {"name": "s", "version": "1"}}))
+        return httpx.Response(200, json=_reply(message, answer if answer is not None else {}))
+
+    def bodies(self, method: str) -> list[dict]:
+        return [json.loads(r.content) for r in self.requests if r.content and json.loads(r.content)["method"] == method]
+
+
+def _reply(message: dict, result: dict) -> dict:
+    return {"jsonrpc": "2.0", "id": message["id"], "result": result}
+
+
+def _events(*blocks: str) -> httpx.Response:
+    return httpx.Response(200, headers={"content-type": "text/event-stream"}, content="".join(blocks).encode())
+
+
+@pytest.fixture
+def scripted(monkeypatch) -> _Scripted:
+    server = _Scripted()
+    _route_clients_to(monkeypatch, httpx.MockTransport(server))
+    return server
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("mode", [{}, {"json_response": True}, {"stateless_http": True}],
+                         ids=["event-stream", "json", "stateless"])
+async def test_an_agentenv_servers_tools_are_listed_and_called_in_each_streamable_http_mode(serve_items, mode):
+    handler, lifespan = await serve_items(**mode)
+    async with lifespan, ToolSession(mcp_url=_URL) as session:
+        tools = {t.name: t for t in await session.list_tools()}
+        added = await session.call_tool("items_add_item", {"item": "crate", "times": 2})
+        listed = await session.call_tool("list_items")
+
+    assert {"items_add_item", "list_items", "echo_after", "explode"} <= set(tools)
+    assert tools["items_add_item"].description == "Add an item to the store."
+    assert tools["items_add_item"].inputSchema["properties"]["item"]["description"] == "The item to add."
+    assert (added.isError, json.loads(added.text)) == (False, {"count": 2})
+    assert json.loads(listed.text) == {"items": ["crate", "crate"]} and handler.items == ["crate", "crate"]
+    assert (session.session_id is None) == ("stateless_http" in mode)
+
+
+@pytest.mark.asyncio
+async def test_a_failing_or_unknown_tool_is_an_error_result_not_an_exception(serve_items):
+    _, lifespan = await serve_items()
+    async with lifespan, ToolSession(mcp_url=_URL) as session:
+        failed = await session.call_tool("explode")
+        unknown = await session.call_tool("no_such_tool")
+        after = await session.call_tool("list_items")
+
+    assert failed.isError and "the tool blew up" in failed.text
+    assert unknown.isError and "no_such_tool" in unknown.text
+    assert not after.isError
+
+
+@pytest.mark.asyncio
+async def test_a_tool_reads_the_role_and_session_a_tool_session_sends_as_its_caller(serve_items):
+    _, lifespan = await serve_items()
+    async with (lifespan, ToolSession(mcp_url=_URL, role="alice@example.com") as alice,
+                ToolSession(mcp_url=_URL) as anonymous, ToolSession(mcp_url=_URL, role="default") as default):
+        whoami = {t.name: t for t in await alice.list_tools()}["whoami"]
+        seen = [json.loads((await session.call_tool("whoami")).text) for session in (alice, anonymous, default)]
+
+    assert not whoami.inputSchema.get("properties")
+    assert seen == [{"role": "alice@example.com", "session": alice.session_id},
+                    {"role": None, "session": anonymous.session_id},
+                    {"role": None, "session": default.session_id}]
+    assert len({alice.session_id, anonymous.session_id, default.session_id}) == 3
+
+
+@pytest.mark.asyncio
+async def test_concurrent_calls_on_one_session_each_get_their_own_reply(serve_items):
+    _, lifespan = await serve_items()
+    async with lifespan, ToolSession(mcp_url=_URL) as session:
+        results = await asyncio.gather(*(session.call_tool("echo_after", {"value": f"v{i}", "seconds": (i % 5) / 50})
+                                         for i in range(25)))
+
+    assert [r.text for r in results] == [f"v{i}" for i in range(25)]
+
+
+@pytest.mark.asyncio
+async def test_a_request_that_outlives_the_timeout_raises_timeout_error_and_the_session_carries_on(serve_items):
+    _, lifespan = await serve_items()
+    async with lifespan, ToolSession(mcp_url=_URL) as session:
+        session.timeout = 0.3
+        started = time.monotonic()
+        with pytest.raises(TimeoutError, match="tools/call did not finish within 0.3s"):
+            await session.call_tool("echo_after", {"value": "late", "seconds": 5})
+        waited = time.monotonic() - started
+        session.timeout = 30
+        assert (await session.call_tool("echo_after", {"value": "on time", "seconds": 0})).text == "on time"
+
+    assert waited < 2
+
+
+def test_text_joins_the_text_blocks_and_skips_the_rest():
+    result = ToolResult(content=[{"type": "text", "text": "first"}, {"type": "image", "data": "...", "mimeType": "image/png"},
+                                 {"type": "text", "text": "second"}])
+    assert result.text == "first\nsecond" and ToolResult().text == ""
+
+
+@pytest.mark.asyncio
+async def test_the_session_sends_its_role_and_headers_echoes_the_session_and_ends_it_on_close(scripted):
+    async with ToolSession(mcp_url=_URL, role="cli", headers={"X-Trace": "t-1"}) as session:
+        await session.list_tools()
+
+    initialize, initialized, listing, delete = scripted.requests
+    assert [r.method for r in scripted.requests] == ["POST", "POST", "POST", "DELETE"]
+    assert all(r.headers[ROLE_HEADER] == "cli" and r.headers["x-trace"] == "t-1" for r in scripted.requests)
+    assert initialize.headers["accept"] == "application/json, text/event-stream"
+    assert "mcp-session-id" not in initialize.headers and "mcp-protocol-version" not in initialize.headers
+    assert json.loads(initialize.content)["params"]["protocolVersion"] == "2025-11-25"
+    assert json.loads(initialized.content) == {"jsonrpc": "2.0", "method": "notifications/initialized"}
+    for later in (initialized, listing, delete):
+        assert (later.headers["mcp-session-id"], later.headers["mcp-protocol-version"]) == ("s-1", "2025-06-18")
+    assert scripted.sessions == set()
+
+
+@pytest.mark.asyncio
+async def test_a_closed_session_opens_again_as_a_new_session(scripted):
+    session = ToolSession(mcp_url=_URL)
+    async with session:
+        pass
+    scripted.sessions.add("s-1")
+    async with session:
+        await session.list_tools()
+
+    second_initialize = [r for r in scripted.requests if r.content and json.loads(r.content)["method"] == "initialize"][1]
+    assert "mcp-session-id" not in second_initialize.headers and session.session_id == "s-1"
+
+
+@pytest.mark.asyncio
+async def test_opening_an_open_session_ends_the_one_it_held_first(scripted):
+    session = await ToolSession(mcp_url=_URL).open()
+    scripted.answers["initialize"] = lambda m: httpx.Response(200, headers={"mcp-session-id": "s-2"}, json=_reply(m, {
+        "protocolVersion": "2025-06-18"}))
+    scripted.sessions.add("s-2")
+    await session.open()
+    await session.close()
+
+    deletes = [r.headers["mcp-session-id"] for r in scripted.requests if r.method == "DELETE"]
+    assert deletes == ["s-1", "s-2"] and scripted.sessions == set()
+
+
+def test_a_session_is_used_and_closed_only_on_the_event_loop_that_opened_it(scripted):
+    session, opener, other = ToolSession(mcp_url=_URL), asyncio.new_event_loop(), asyncio.new_event_loop()
+    try:
+        opener.run_until_complete(session.open())
+        with pytest.raises(RuntimeError, match="opened on another event loop"):
+            other.run_until_complete(session.call_tool("t"))
+        with pytest.raises(RuntimeError, match="opened on another event loop"):
+            other.run_until_complete(session.close())
+        assert not opener.run_until_complete(session.call_tool("t")).isError
+        opener.run_until_complete(session.close())
+    finally:
+        opener.close()
+        other.close()
+
+    assert [r.method for r in scripted.requests].count("DELETE") == 1 and scripted.sessions == set()
+
+
+@pytest.mark.asyncio
+async def test_tools_list_follows_cursors_until_the_last_page(scripted):
+    pages = {None: (["a", "b"], "p2"), "p2": (["c"], "p3"), "p3": (["d"], None)}
+
+    def page(message):
+        names, cursor = pages[message["params"].get("cursor")]
+        return httpx.Response(200, json=_reply(message, {"tools": [{"name": n} for n in names],
+                                                         **({"nextCursor": cursor} if cursor else {})}))
+    scripted.answers["tools/list"] = page
+
+    async with ToolSession(mcp_url=_URL) as session:
+        assert [t.name for t in await session.list_tools()] == ["a", "b", "c", "d"]
+    assert [b["params"] for b in scripted.bodies("tools/list")] == [{}, {"cursor": "p2"}, {"cursor": "p3"}]
+
+
+@pytest.mark.asyncio
+async def test_an_event_stream_reply_is_found_among_comments_priming_events_notifications_and_other_ids(scripted):
+    def stream(message):
+        reply = json.dumps(_reply(message, {"content": [{"type": "text", "text": "found"}]}), indent=1)
+        return _events(
+            ": keep-alive\n\n",
+            "id: prime-1\ndata:\n\n",
+            'event: message\ndata: {"jsonrpc": "2.0", "method": "notifications/progress", "params": {}}\n\n',
+            f'data: {json.dumps(_reply({"id": 999}, {"content": []}))}\n\n',
+            "event: ping\ndata: {}\n\n",
+            "".join(f"data: {line}\n" for line in reply.splitlines()) + "\n",
+        )
+    scripted.answers["tools/call"] = stream
+
+    async with ToolSession(mcp_url=_URL) as session:
+        assert (await session.call_tool("t")).text == "found"
+
+
+@pytest.mark.asyncio
+async def test_a_session_the_server_dropped_raises_and_says_the_state_may_be_gone(scripted):
+    async with ToolSession(mcp_url=_URL) as session:
+        scripted.sessions.clear()
+        with pytest.raises(ToolSessionError, match="no longer knows session s-1.*state may be gone"):
+            await session.call_tool("t")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("answer, match", [
+    (lambda m: httpx.Response(200, json={"jsonrpc": "2.0", "id": m["id"], "error": {"code": -32602, "message": "bad args"}}),
+     r"tools/call failed: bad args \(code -32602\)"),
+    (lambda m: httpx.Response(500, text="upstream exploded"), "tools/call: HTTP 500 from http://env/mcp: upstream exploded"),
+    (lambda m: httpx.Response(200, headers={"content-type": "application/json"}, content=b"{not json"),
+     "tools/call: unreadable reply"),
+    (lambda m: _events("data: {broken\n\n"), "tools/call: unreadable reply"),
+    (lambda m: _events('data: {"jsonrpc": "2.0", "method": "notifications/message"}\n\n'),
+     "tools/call: the event stream ended before the reply"),
+    (lambda m: _events(f"data: {json.dumps(_reply(m, {}))}"), "tools/call: the event stream ended before the reply"),
+    (lambda m: httpx.Response(200, headers={"content-type": "text/plain"}, content=b"hi"),
+     "tools/call: unexpected content type 'text/plain'"),
+    (lambda m: httpx.Response(200, json=[_reply(m, {})]), "tools/call: the reply is not a JSON-RPC object"),
+    (lambda m: httpx.Response(200, json={"jsonrpc": "2.0", "id": m["id"], "result": "ok"}),
+     "tools/call: the reply has no result object"),
+    (lambda m: httpx.Response(200, json=_reply(m, {"content": "not a list"})), "tools/call: unreadable result"),
+    (lambda m: httpx.Response(200, json=_reply(m, {"content": [{"type": "text"}]})), "tools/call: unreadable result"),
+    (lambda m: httpx.Response(200, json=_reply(m, {"content": [{"type": "text", "text": 7}]})),
+     "tools/call: unreadable result"),
+], ids=["jsonrpc-error", "http-500", "bad-json", "bad-event-json", "no-reply-in-stream", "unterminated-event",
+        "wrong-content-type", "batch-reply", "result-not-object", "result-wrong-shape", "text-block-without-text",
+        "text-block-with-a-number"])
+async def test_a_failure_at_the_mcp_level_raises_a_tool_session_error(scripted, answer, match):
+    scripted.answers["tools/call"] = answer
+    async with ToolSession(mcp_url=_URL) as session:
+        with pytest.raises(ToolSessionError, match=match):
+            await session.call_tool("t")
+
+
+@pytest.mark.asyncio
+@pytest.mark.parametrize("result", [{"tools": [{"description": "nameless"}]}, {"tools": 7}, {"tools": None}, {}],
+                         ids=["nameless-tool", "tools-not-a-list", "tools-null", "tools-missing"])
+async def test_a_tools_list_that_cannot_be_read_raises_a_tool_session_error(scripted, result):
+    scripted.answers["tools/list"] = result
+    async with ToolSession(mcp_url=_URL) as session:
+        with pytest.raises(ToolSessionError, match="tools/list: unreadable result"):
+            await session.list_tools()
+
+
+@pytest.mark.asyncio
+async def test_a_failed_initialize_raises_and_leaves_the_session_closed(scripted):
+    scripted.answers["initialize"] = lambda m: httpx.Response(503, text="starting up")
+    session = ToolSession(mcp_url=_URL)
+    with pytest.raises(ToolSessionError, match="initialize: HTTP 503"):
+        await session.open()
+    with pytest.raises(RuntimeError, match="the ToolSession is not open"):
+        await session.list_tools()
+
+
+@pytest.mark.asyncio
+async def test_closing_after_the_server_is_gone_does_not_raise(monkeypatch):
+    async def gone_on_delete(request: httpx.Request) -> httpx.Response:
+        if request.method == "DELETE":
+            raise httpx.ConnectError("connection refused", request=request)
+        message = json.loads(request.content)
+        if "id" not in message:
+            return httpx.Response(202)
+        return httpx.Response(200, headers={"mcp-session-id": "s-9"}, json=_reply(message, {"protocolVersion": "2025-11-25"}))
+    _route_clients_to(monkeypatch, httpx.MockTransport(gone_on_delete))
+
+    async with ToolSession(mcp_url=_URL) as session:
+        assert session.session_id == "s-9"
+    await session.close()
+
+
+@pytest.mark.asyncio
+async def test_closing_waits_for_the_server_no_longer_than_the_sessions_timeout(monkeypatch):
+    async def stalls_on_delete(request: httpx.Request) -> httpx.Response:
+        if request.method == "DELETE":
+            await asyncio.sleep(30)
+        message = json.loads(request.content or b"{}")
+        if "id" not in message:
+            return httpx.Response(202)
+        return httpx.Response(200, headers={"mcp-session-id": "s-2"}, json=_reply(message, {"protocolVersion": "2025-11-25"}))
+    _route_clients_to(monkeypatch, httpx.MockTransport(stalls_on_delete))
+
+    session = await ToolSession(mcp_url=_URL).open()
+    session.timeout = 0.3
+    started = time.monotonic()
+    await session.close()
+    assert time.monotonic() - started < 1