agentenv-framework-protocol 0.1.481__tar.gz → 0.1.483__tar.gz

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/PKG-INFO

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

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/pyproject.toml

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

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/agent_env_environment.py

@@ -309,7 +309,8 @@ class AgentEnvApplication(ABC):
         self._app: Any = None
         ext_handlers = _served_extensions(handler, _discover_extensions(handler))
         environment_card = _merge_extensions(environment_card, ext_handlers + _declared_extensions(handler, ext_handlers))
-        tool_handlers = _served_tools(handler, _with_forwarded(_discover_tools(handler, environment_card.name), handler))
+        tool_handlers = _named_tools(handler, _served_tools(
+            handler, _with_forwarded(_discover_tools(handler, environment_card.name), handler)))
         if tool_handlers and not self.supports_tools:
             raise ValueError(f"@tool methods require a FastMCP-backed application; {type(self).__name__} cannot serve MCP tools")
         self._resources = _discover_resources(handler)
@@ -1107,11 +1108,15 @@ def _with_parts(method: Callable, parts: dict[str, str]) -> Callable:
 
 
 def _instructions(handler: Any) -> str | None:
-    """What the handler's @server_instructions method returns; None without one."""
+    """What the handler's @server_instructions method returns, as its ``served_instructions`` serves it; None without
+    one."""
     marked = [method for method, _marker in _marked_members(handler, _INSTRUCTIONS_ATTR)]
     if len(marked) > 1:
         raise ValueError(f"an environment has one @server_instructions method, not {sorted(m.__name__ for m in marked)}")
-    return marked[0]() if marked else None
+    if not marked:
+        return None
+    hook = getattr(handler, "served_instructions", None)
+    return hook(marked[0]()) if hook is not None else marked[0]()
 
 
 def _discover_methods(handler: Any) -> dict:
@@ -1320,6 +1325,20 @@ def _served_tools(handler: Any, tool_handlers: list) -> list:
     return [(descriptor, by_name[descriptor.name]) for descriptor in chosen]
 
 
+def _named_tools(handler: Any, tool_handlers: list) -> list:
+    """The tools as the handler's ``serve_tools_as`` names and describes them, in their order; as they are without one."""
+    hook = getattr(handler, "serve_tools_as", None)
+    if hook is None:
+        return tool_handlers
+    named = list(hook([descriptor for descriptor, _fn in tool_handlers]))
+    if len(named) != len(tool_handlers):
+        raise ValueError(f"serve_tools_as returned {len(named)} tools for {len(tool_handlers)}")
+    names = [descriptor.name for descriptor in named]
+    if len(set(names)) != len(names):
+        raise ValueError(f"serve_tools_as named two tools alike: {sorted({n for n in names if names.count(n) > 1})}")
+    return [(descriptor, fn) for descriptor, (_old, fn) in zip(named, tool_handlers)]
+
+
 def _merge_tools(card: EnvironmentCard, tool_handlers: list) -> EnvironmentCard:
     """Advertise decorator-declared tools under card.capabilities; card-declared names win."""
     if not tool_handlers:

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/__init__.py

@@ -82,7 +82,7 @@ from .dataplane import part_bytes
 from .keys import PRINTABLE_KEYS
 from .manifest import ManifestSegment, RecordingManifest
 from .platform import Platform
-from .settings import SETTINGS_ENV, ComputerSettings
+from .settings import SETTINGS_ENV, TOOL_PREFIX_ENV, ComputerSettings, tool_prefix_problem
 
 if TYPE_CHECKING:
     from .card import (
@@ -127,7 +127,7 @@ __all__ = [
     "Launch", "Ready", "Packages", "AptSource", "Download", "RunScript",
     "AppDeclaration", "AppOs",
     "APP_SETTINGS_ENV", "part_bytes",
-    "Display", "Image", "Effect", "ExecResult", "ReadyCheck", "Platform", "ComputerSettings", "SETTINGS_ENV",
+    "Display", "Image", "Effect", "ExecResult", "ReadyCheck", "Platform", "ComputerSettings", "SETTINGS_ENV", "TOOL_PREFIX_ENV", "tool_prefix_problem",
     "Tab", "PageState", "PageDialog", "FileChooser",
     "PRINTABLE_KEYS",
     "display", "set_display", "capture", "click", "drag", "scroll", "type_text", "press",

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/driver.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 
 import asyncio
 import logging
+import os
 from pathlib import Path
 from typing import Any, Callable, ClassVar, Literal, Optional
 
@@ -13,9 +14,9 @@ from starlette.requests import Request
 from starlette.responses import Response
 from starlette.websockets import WebSocket
 
-from ..agent_env_environment import (_CARD_CONFIG_ATTR, AgentEnvEnvironment, AgentEnvFastMCPApplication,
-                                     AgentEnvError, _error_response, add_websocket_route, control_check,
-                                     environment_card)
+from ..agent_env_environment import (_CARD_CONFIG_ATTR, _TOOL_ATTR, AgentEnvEnvironment, AgentEnvFastMCPApplication,
+                                     AgentEnvError, _error_response, _marked_members, add_websocket_route,
+                                     control_check, environment_card)
 from ..tool_context import ToolContext
 from ..types import EnvironmentCard, EnvironmentExtension, EnvironmentTool
 from . import _linux, apps, card, svc
@@ -27,8 +28,9 @@ from .operations import ReadyCheck, check_class, default_for
 from .platform import Platform, detect
 from .recording import Recording
 from .runtime import ComputerRuntime
-from .settings import ComputerSettings, load_settings
-from .tools import Tools
+from .prefix import ToolPrefix
+from .settings import TOOL_PREFIX_ENV, ComputerSettings, load_settings, tool_prefix_problem
+from .tools import COMPUTER_TOOLS, Tools
 
 #: The caller every call comes from until agents carry an identity of their own.
 DEFAULT_IDENTITY = "default"
@@ -99,9 +101,15 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         check_class(cls)
         check_features(cls)
 
-    def __init__(self, settings: ComputerSettings | None = None, platform: Platform | None = None) -> None:
+    def __init__(self, settings: ComputerSettings | None = None, platform: Platform | None = None,
+                 tool_prefix: str | None = None) -> None:
         self.settings = settings if settings is not None else load_settings(model=type(self).Settings)
         self.platform = platform if platform is not None else detect()
+        prefix = os.environ.get(TOOL_PREFIX_ENV, "") if tool_prefix is None else tool_prefix
+        if problem := tool_prefix_problem(prefix):
+            raise ValueError(problem)
+        #: The start of every name it serves a tool under: the deploy's ``AGENTENV_TOOL_PREFIX``, none by default.
+        self._computer_prefix = ToolPrefix(prefix)
         self._computer = ComputerRuntime(self)
         #: The routes each app's card opens to agents, by app, read once it answers.
         self._computer_agent_routes: dict[str, list[str]] = {}
@@ -113,7 +121,7 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         running its ``__init__``: what a ``computer_driver`` env records for each platform it supports. The card
         hooks may read the class and the base class's state, not what a subclass's ``__init__`` sets."""
         driver = cls.__new__(cls)
-        ComputerDriverEnvironment.__init__(driver, settings=cls.Settings(), platform=platform)
+        ComputerDriverEnvironment.__init__(driver, settings=cls.Settings(), platform=platform, tool_prefix="")
         config = dict(getattr(cls, _CARD_CONFIG_ATTR, None) or {})
         card = EnvironmentCard(**{**config, "name": config.get("name") or cls.__name__})
         return AgentEnvFastMCPApplication(card, driver).environment_card
@@ -203,6 +211,17 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
     def served_tools(self, tools: list[EnvironmentTool]) -> list[EnvironmentTool]:
         return card.served_tools(self, tools)
 
+    def serve_tools_as(self, tools: list[EnvironmentTool]) -> list[EnvironmentTool]:
+        return self._computer_prefix.tools(tools)
+
+    def served_instructions(self, text: str) -> str:
+        return self._computer_prefix.instructions(text, self._computer_other_tools())
+
+    def _computer_other_tools(self) -> list[str]:
+        """Its driver's own and forwarded tools, whose text stays as written, by their own names."""
+        return [marker.name for _member, marker in _marked_members(self, _TOOL_ATTR) if marker.name not in COMPUTER_TOOLS] + [
+            forwarded.tool.name for forwarded in self.forwarded_tools()]
+
     def served_extensions(self, extensions: list[EnvironmentExtension]) -> list[EnvironmentExtension]:
         return card.served_extensions(self, extensions)
 
@@ -213,7 +232,8 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         return card.extension_params(self, uri)
 
     def declared_extensions(self) -> list[EnvironmentExtension]:
-        return card.declared_extensions(self)
+        return [extension.model_copy(update={"description": self._computer_prefix.text(extension.description)})
+                for extension in card.declared_extensions(self)]
 
     def _computer_require_init(self) -> None:
         if self._computer is None:

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/extensions.py

@@ -79,8 +79,8 @@ class Extensions:
                                    self.settings.default_norm_scale)
         self.settings = self.settings.model_copy(update={"default_space": space, "default_norm_scale": scale})
         for tool in self.mounted_card().capabilities.tools or []:
-            if tool.name in card.POINT_TOOLS:
-                await self.update_tool(tool.name, description=card.point_description(self, tool.name))
+            if (own := self._computer_prefix.own(tool.name)) in card.POINT_TOOLS:
+                await self.update_tool(tool.name, description=self._computer_prefix.text(card.point_description(self, own)))
         return await self._computer_spaces_get()
 
     @extension(COMPUTER_KEYBOARD, op="get", method="GET",

agentenv_framework_protocol-0.1.483/src/agentenv_protocol/computer/prefix.py

@@ -0,0 +1,51 @@
+"""A computer's tool prefix: the names it serves its tools under, so several computers serve theirs side by side on
+one gateway. The SDK's ``computer_*`` names in its text are rewritten to them; its driver's own and forwarded tools
+keep their text as written, and a sentence tells an agent how those are named."""
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+
+from ..types import EnvironmentTool
+from .tools import COMPUTER_TOOLS
+
+#: The SDK's tool names, and a ``computer_*`` family of them, each as a whole word.
+_SDK_NAMES = re.compile(r"(?<![\w-])(?:" + "|".join([*map(re.escape, sorted(COMPUTER_TOOLS, key=len, reverse=True)),
+                                                      r"computer_(?:[a-z]+_)*\*"]) + r")(?![\w-])")
+
+
+class ToolPrefix:
+    """``prefix``, the start of every name a computer serves a tool under; none leaves every name as it is."""
+
+    def __init__(self, prefix: str) -> None:
+        self.prefix = prefix
+
+    def served(self, name: str) -> str:
+        """The name the tool ``name`` is served under."""
+        return f"{self.prefix}{name}"
+
+    def own(self, served: str) -> str:
+        """A served tool's own name."""
+        return served.removeprefix(self.prefix)
+
+    def text(self, text: str | None) -> str | None:
+        """``text`` naming the SDK's tools as they are served; any other name stays as written."""
+        return _SDK_NAMES.sub(lambda m: self.prefix + m.group(0), text) if self.prefix and text else text
+
+    def tools(self, tools: list[EnvironmentTool]) -> list[EnvironmentTool]:
+        """``tools`` under their served names, the SDK's own with their descriptions' names served too."""
+        return [tool.model_copy(update={"name": self.served(tool.name), **(
+            {"description": self.text(tool.description)} if tool.name in COMPUTER_TOOLS else {})}) for tool in tools]
+
+    def rule(self, others: Iterable[str]) -> str | None:
+        """The sentence telling an agent how ``others``, the tools whose text stays as written, are served; None
+        without a prefix or any of them."""
+        example = next(iter(others), None)
+        if not self.prefix or example is None:
+            return None
+        return (f"This computer serves its tools under `{self.prefix}`: a tool this text names without `{self.prefix}` is "
+                f"served with it, so `{example}` is `{self.prefix}{example}`. Names inside a tool's arguments stay as written.")
+
+    def instructions(self, text: str, others: Iterable[str]) -> str:
+        """An MCP server's instructions as the computer serves them: after the rule, if there is one, its names served."""
+        return "\n\n".join(part for part in (self.rule(others), self.text(text)) if part)

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/runtime.py

@@ -116,7 +116,7 @@ class ComputerRuntime:
         async with self.queue.turn(self.driver.settings.queue_wait_s):
             if operation in DIALOG_BLOCKS and self.has("page") and (dialog := (await self.page_now()).dialog):
                 raise DialogOpen(f'a {dialog.type} dialog is open on the page: "{dialog.message}"; answer it with '
-                                 "computer_dialog first")
+                                 f"{self.driver._computer_prefix.served('computer_dialog')} first")
             if mapped and frame is not None:
                 self.frames.check_current(frame, await self.display_now())
             if at_pointer:

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/settings.py

@@ -3,12 +3,29 @@ from __future__ import annotations
 
 import json
 import os
+import re
 from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
 
 SETTINGS_ENV = "AGENTENV_COMPUTER_SETTINGS"
+#: The prefix a deploy gives the names of the computer's tools, so several computers serve them side by side.
+TOOL_PREFIX_ENV = "AGENTENV_TOOL_PREFIX"
+_TOOL_PREFIX = re.compile(r"[A-Za-z0-9_-]*")
+#: The longest a tool prefix may be, its separator included, so a prefixed name stays well within the 64 characters
+#: model APIs take for a tool's name.
+MAX_TOOL_PREFIX = 16
+
+
+def tool_prefix_problem(prefix: str) -> str | None:
+    """What's wrong with ``prefix`` as a tool prefix, or None: only what a tool's name may hold, at most
+    ``MAX_TOOL_PREFIX`` characters."""
+    if not _TOOL_PREFIX.fullmatch(prefix):
+        return f"tool prefix {prefix!r} holds characters a tool's name can't"
+    if len(prefix) > MAX_TOOL_PREFIX:
+        return f"tool prefix {prefix!r} is {len(prefix)} characters, and a tool prefix is at most {MAX_TOOL_PREFIX}"
+    return None
 
 Space = Literal["frame", "norm"]
 

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/skill.py

@@ -61,11 +61,14 @@ async def skill(driver: ComputerDriverEnvironment) -> tuple[str, str, dict[str,
     if notes := driver.notes.strip():
         sections += ["## Notes", notes]
     body = "\n\n".join(sections) + "\n"
+    prefix = driver._computer_prefix
+    lead = f"{rule}\n\n" if (rule := prefix.rule(driver._computer_other_tools())) else ""
     if bundled is None:
-        return description, body, {}
+        return prefix.text(description), prefix.text(lead + body), {}
     own_description, own_body, files = bundled
-    return (f"{own_description} This computer: {system}, {display.width}x{display.height}, and its computer_* tools.",
-            own_body.rstrip() + "\n\n" + body, files)
+    return (prefix.text(f"{own_description} This computer: {system}, {display.width}x{display.height}, and its "
+                        "computer_* tools."),
+            prefix.text(lead + own_body.rstrip() + "\n\n" + body), files)
 
 
 def _input(driver: ComputerDriverEnvironment) -> str:

{agentenv_framework_protocol-0.1.481 → agentenv_framework_protocol-0.1.483}/src/agentenv_protocol/computer/tools.py

@@ -9,7 +9,7 @@ from typing import TYPE_CHECKING, Annotated, Any, Callable, Literal, Optional
 from mcp.types import CallToolResult
 from pydantic import Field
 
-from ..agent_env_environment import tool
+from ..agent_env_environment import _TOOL_ATTR, tool
 from ..tool_context import ToolContext
 from .errors import InvalidArgument, Unsupported
 from .frames import Frame
@@ -201,7 +201,8 @@ class Tools:
             raise InvalidArgument(f"text is at most {self.max_text_length} characters on this computer, got {len(text)}")
         control = sorted({f"U+{ord(c):04X}" for c in text if c not in "\n\t" and unicodedata.category(c) == "Cc"})
         if control:
-            raise InvalidArgument(f"text has control characters {control}; press keys with computer_key")
+            raise InvalidArgument(f"text has control characters {control}; press keys with "
+                                  f"{self._computer_prefix.served('computer_key')}")
         return await computer.act(ctx, "type_text", (text,), frame=computer.frames.latest(self.caller_identity(ctx)),
                                   screenshot=screenshot, summary=f"Typed {len(text)} characters")
 
@@ -509,3 +510,7 @@ def _check_range(name: str, value: int, low: int, high: int) -> None:
 def _display(frame: Frame) -> str:
     d = frame.display
     return f"{d.width}×{d.height}" + (f" at scale {d.scale:g}" if d.scale != 1 else "")
+
+
+#: The tools the SDK serves on every computer, by their own names.
+COMPUTER_TOOLS: tuple[str, ...] = tuple(sorted(name for name, member in vars(Tools).items() if hasattr(member, _TOOL_ATTR)))

agentenv_framework_protocol-0.1.483/tests/test_computer_tool_prefix.py

@@ -0,0 +1,153 @@
+"""A computer deployed with a tool prefix serves every tool under it, and names its tools that way wherever it names
+them: the card, tools/list, its skill, its extensions' descriptions and its errors. Without one, nothing changes."""
+from __future__ import annotations
+
+import re
+
+import pytest
+
+pytest.importorskip("mcp.server.fastmcp")
+pytest.importorskip("PIL")
+
+from computer_fake import LINUX, FakeDriver, http_client, mcp_session  # noqa: E402
+from mcp.types import CallToolResult, TextContent  # noqa: E402
+
+from agentenv_protocol import EnvironmentTool, ForwardedTool, server_instructions  # noqa: E402
+from agentenv_protocol.computer import TOOL_PREFIX_ENV  # noqa: E402
+
+PREFIX = "desktop_"
+UNPREFIXED = re.compile(r"(?<![\w-])computer_")
+
+
+async def _names(driver) -> tuple[set, set]:
+    async with http_client(driver) as http, mcp_session(driver) as session:
+        card = (await http.get("/.well-known/agent-env.json")).json()
+        listed = {tool.name for tool in (await session.list_tools()).tools}
+    return {tool["name"] for tool in card["capabilities"]["tools"]}, listed
+
+
+@pytest.mark.asyncio
+async def test_a_deploys_tool_prefix_names_every_tool_on_the_card_and_in_tools_list(monkeypatch):
+    own_card, own_listed = await _names(FakeDriver())
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    driver = FakeDriver()
+    card, listed = await _names(driver)
+    assert card == listed == {PREFIX + name for name in own_card} and own_card == own_listed
+    async with mcp_session(driver) as session:
+        shot = await session.call_tool(f"{PREFIX}computer_screenshot", {})
+        unknown = await session.call_tool("computer_screenshot", {})
+    assert not shot.isError and any(part.type == "image" for part in shot.content)
+    assert unknown.isError
+
+
+def test_the_declaration_a_driver_env_stores_names_the_tools_without_the_deploys_prefix(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    names = {tool.name for tool in FakeDriver.declaration(LINUX).capabilities.tools}
+    assert "computer_screenshot" in names and not any(name.startswith(PREFIX) for name in names)
+
+
+@pytest.mark.asyncio
+async def test_its_skill_its_extensions_and_its_notes_name_the_tools_as_it_serves_them(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    monkeypatch.setattr(FakeDriver, "notes", "Take a computer_screenshot first; desktop_computer_click is already right.")
+    async with http_client(FakeDriver()) as http:
+        skill = (await http.get("/agentenv/ext/skill/get", params={"name": "desktop"})).json()
+        card = (await http.get("/.well-known/agent-env.json")).json()
+    text = skill["description"] + skill["skill_md"]
+    assert f"`{PREFIX}computer_screenshot`" in text and f"`{PREFIX}computer_*`" in text and f"`{PREFIX}computer_click`" in text
+    assert "Take a desktop_computer_screenshot first; desktop_computer_click is already right." in text
+    assert not UNPREFIXED.search(text) and "desktop_desktop_" not in text and "serves its tools under" not in text
+    descriptions = " ".join(e["description"] for e in card["capabilities"]["extensions"] if e.get("description"))
+    assert f"The seven {PREFIX}computer_* tools" in descriptions and not UNPREFIXED.search(descriptions)
+    tools = " ".join(t.get("description") or "" for t in card["capabilities"]["tools"])
+    assert not UNPREFIXED.search(tools)
+
+
+@pytest.mark.asyncio
+async def test_an_error_names_the_tool_to_use_instead_as_it_is_served(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    async with mcp_session(FakeDriver()) as session:
+        refused = await session.call_tool(f"{PREFIX}computer_type", {"text": "a\x07b"})
+    assert refused.isError and f"press keys with {PREFIX}computer_key" in refused.content[0].text
+
+
+@pytest.mark.asyncio
+async def test_tool_access_rules_name_the_tools_as_it_serves_them(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    driver = FakeDriver()
+    async with http_client(driver) as http, mcp_session(driver) as session:
+        disabled = await http.post("/tools/disable", json={"role": "default", "tools": [f"{PREFIX}computer_click"]})
+        listed = {tool.name for tool in (await session.list_tools()).tools}
+        refused = await session.call_tool(f"{PREFIX}computer_click", {"x": 1, "y": 1})
+    assert disabled.status_code == 200
+    assert f"{PREFIX}computer_click" not in listed and f"{PREFIX}computer_screenshot" in listed
+    assert refused.isError and "is disabled for role 'default'" in refused.content[0].text
+
+
+@pytest.mark.asyncio
+async def test_setting_the_default_space_rewrites_the_prefixed_point_tools(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    driver = FakeDriver()
+    async with http_client(driver) as http, mcp_session(driver) as session:
+        await http.post("/agentenv/ext/computer-spaces/set", json={"default_space": "norm", "default_norm_scale": 1000})
+        after = {t.name: t.description for t in (await session.list_tools()).tools}
+    assert "norm space by default: 0 to 1000" in after[f"{PREFIX}computer_click"]
+
+
+@pytest.mark.parametrize("prefix, problem", [
+    ("desk top_", "holds characters a tool's name can't"),
+    ("desktop/", "holds characters a tool's name can't"),
+    ("décor_", "holds characters a tool's name can't"),
+    ("accounting-desk1_", "is 17 characters, and a tool prefix is at most 16"),
+])
+def test_a_prefix_a_tool_name_cant_hold_or_that_is_too_long_is_refused(monkeypatch, prefix, problem):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, prefix)
+    with pytest.raises(ValueError, match=problem):
+        FakeDriver()
+
+
+@pytest.mark.asyncio
+async def test_a_prefix_of_sixteen_characters_is_taken(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, "accounting-desk_")
+    card, _listed = await _names(FakeDriver())
+    assert "accounting-desk_computer_pointer_position" in card
+
+
+class Forwarding(FakeDriver):
+    """A driver forwarding another program's batch tool, whose steps name that program's own actions."""
+
+    def forwarded_tools(self):
+        schema = {"type": "object", "properties": {"tool": {"type": "string", "enum": ["click", "double_click"]}}}
+        return [ForwardedTool(EnvironmentTool(name="run_steps", description="Run click or double_click in one call.",
+                                              inputSchema=schema), self.steps)]
+
+    async def steps(self, tool):
+        return CallToolResult(content=[TextContent(type="text", text=f"ran {tool}")])
+
+    @server_instructions
+    def instructions(self):
+        return "Act through run_steps, and take a computer_screenshot first."
+
+
+@pytest.mark.asyncio
+async def test_a_forwarded_tool_keeps_its_own_text_and_the_skill_and_instructions_lead_with_the_prefix_rule(monkeypatch):
+    monkeypatch.setenv(TOOL_PREFIX_ENV, PREFIX)
+    driver = Forwarding()
+    instructions = driver.create_app().instructions
+    async with http_client(driver) as http, mcp_session(driver) as session:
+        tools = {tool.name: tool for tool in (await session.list_tools()).tools}
+        ran = await session.call_tool(f"{PREFIX}run_steps", {"tool": "click"})
+        skill = (await http.get("/agentenv/ext/skill/get", params={"name": "desktop"})).json()
+    forwarded = tools[f"{PREFIX}run_steps"]
+    assert forwarded.description == "Run click or double_click in one call."
+    assert forwarded.inputSchema["properties"]["tool"]["enum"] == ["click", "double_click"]
+    assert not ran.isError and ran.content[0].text == "ran click"
+    rule = (f"This computer serves its tools under `{PREFIX}`: a tool this text names without `{PREFIX}` is served with it, "
+            f"so `run_steps` is `{PREFIX}run_steps`. Names inside a tool's arguments stay as written.")
+    assert skill["skill_md"].partition("---\n\n")[2].startswith(rule)
+    assert instructions == f"{rule}\n\nAct through run_steps, and take a {PREFIX}computer_screenshot first."
+
+
+def test_without_a_prefix_a_forwarding_drivers_instructions_are_its_own(monkeypatch):
+    monkeypatch.delenv(TOOL_PREFIX_ENV, raising=False)
+    assert Forwarding().create_app().instructions == "Act through run_steps, and take a computer_screenshot first."