Skip to content
Open
14 changes: 11 additions & 3 deletions src/agent_env/env/envs/_deployment.py
Original file line number Diff line number Diff line change
Expand Up @@ -141,8 +141,15 @@ async def load_by_signed_url(env: MCPServerEnv | WebsiteEnv, environment_artifac
if urls[path] is None:
raise RuntimeError(f"{deployed_by}, so its server fetches {file.object_url} itself, and {type(stores[path]).__name__} "
"can't sign a URL for it; loading into such an env needs an object store that signs URLs (S3, Cloud Storage)")
await protocol_v1.reset_data(base_url, timeout=timeout)
await protocol_v1.add_data(base_url, file_parts(environment_artifact, files, urls), timeout=timeout)
headers = data_plane_headers(env, base_url)
await protocol_v1.reset_data(base_url, timeout=timeout, headers=headers)
await protocol_v1.add_data(base_url, file_parts(environment_artifact, files, urls), timeout=timeout, headers=headers)


def data_plane_headers(env: MCPServerEnv | WebsiteEnv, url: str) -> dict[str, str] | None:
"""The headers a call to ``url`` sends of ``env``'s record's control token; None, which leaves the call to a run's
or a multi env's grant, when the record gives it none: no record, no token, or an address outside the record's."""
return (env._deployed.control_headers_for(url) or None) if env._deployed is not None else None


async def reset_server_data(env: MCPServerEnv | WebsiteEnv, *, mcp: bool) -> bool:
Expand All @@ -161,7 +168,8 @@ async def reset_server_data(env: MCPServerEnv | WebsiteEnv, *, mcp: bool) -> boo
child = env._deployed.child_env(name, mcp=mcp) if env._deployed is not None and env._deployed.environment_card else None
if child is not None and child.serves(METHOD_RESET) is False:
return False
await protocol_v1.reset_data(base_url, timeout=DATA_PLANE_LOAD_TIMEOUT_S)
await protocol_v1.reset_data(base_url, timeout=DATA_PLANE_LOAD_TIMEOUT_S,
headers=data_plane_headers(env, base_url))
elif builtin is None:
return False
else:
Expand Down
9 changes: 6 additions & 3 deletions src/agent_env/env/envs/mcp_server.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,8 @@
from agent_env.env import legacy_protocol
from agent_env.env.envs._deployment import (
as_builtin, builtin_provider_for, close_deployed, close_replaced, deploy_refusal, deploy_through_provider, host_staging_refusal,
file_parts, legacy_load_file, load_by_signed_url, plugin_provider_like_a_builtin, provider_or_class, reset_server_data,
data_plane_headers, file_parts, legacy_load_file, load_by_signed_url, plugin_provider_like_a_builtin, provider_or_class,
reset_server_data,
staged_paths,
)
from agent_env.env.gateway import GatewayMode
Expand Down Expand Up @@ -186,8 +187,10 @@ async def load_environment_artifact(self, environment_artifact: EnvironmentArtif
# reset_data previously took the client default (30s), tighter than the load it
# precedes -- dropping and recreating a large service's schemas can plausibly
# exceed that. Give it the same budget as the load it belongs to.
await protocol_v1.reset_data(base_url, timeout=timeout)
await protocol_v1.add_data(base_url, file_parts(environment_artifact, files, staged), timeout=timeout)
headers = data_plane_headers(self, base_url)
await protocol_v1.reset_data(base_url, timeout=timeout, headers=headers)
await protocol_v1.add_data(base_url, file_parts(environment_artifact, files, staged), timeout=timeout,
headers=headers)
finally:
if folder is not None:
await self._remove_from_container(folder)
Expand Down
18 changes: 15 additions & 3 deletions src/agent_env/env/envs/multi_env.py
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,7 @@
from typing import TYPE_CHECKING, Any, Callable, ClassVar, Optional

import yaml
from agentenv_protocol import client as protocol_v1

logger = logging.getLogger(__name__)

Expand Down Expand Up @@ -461,11 +462,13 @@ async def load_environment_artifact(self, environment_artifact: EnvironmentArtif
# MCP servers are checked first; if a website shares the same environment_name, the MCP server wins.
for env in self.mcp_server_envs:
if env.environment_name == environment_artifact.environment_name:
await env.load_environment_artifact(environment_artifact)
with _record_grant(self._deployed):
await env.load_environment_artifact(environment_artifact)
return
for env in self.website_envs:
if env.environment_name == environment_artifact.environment_name:
await env.load_environment_artifact(environment_artifact)
with _record_grant(self._deployed):
await env.load_environment_artifact(environment_artifact)
return
if (computer := self._computers.holding(environment_artifact.environment_name)) is not None:
await computer.load_environment_artifact(environment_artifact)
Expand Down Expand Up @@ -1067,7 +1070,8 @@ async def reset(self, deployed: DeployedEnv) -> None:
for env in services.mcp_server_envs),
*((f"website {env.environment_name!r}", reset_server_data(env, mcp=False))
for env in services.website_envs)]
results = await _multi_computers.each(self.id, "reset", resets)
with _record_grant(deployed):
results = await _multi_computers.each(self.id, "reset", resets)
for (child, _), result in zip(resets, results):
if result is False:
logger.info(f"multi env '{self.id}': {child} serves no reset and takes no load, so it stays as it is")
Expand Down Expand Up @@ -1122,6 +1126,14 @@ def _gateway_state_provider(env: MultiEnv) -> DatabaseStateProvider | None:
return env._env_provider._state_provider if isinstance(env._env_provider, EnvironmentGatewayProvider) else None


def _record_grant(deployed: Optional[DeployedEnv]):
"""The grant of ``deployed``'s control token to calls under its address and its gateway's, for a child env that a
name it shares with another keeps from the record (``_hand_record_to_child_envs``), whose calls go to the gateway."""
if deployed is None:
return protocol_v1.authorized({})
return protocol_v1.authorized({url: deployed.control_headers for url in (deployed.environment_url, gateway_url_of(deployed))})


def _hand_record_to_child_envs(env: MultiEnv, deployed: DeployedEnv) -> None:
"""Give each child env the record its loads read the card from; a name an MCP server and a website share keeps the live probe, since the card can't tell them apart by name."""
shared = {c.environment_name for c in env.mcp_server_envs} & {c.environment_name for c in env.website_envs}
Expand Down
8 changes: 5 additions & 3 deletions src/agent_env/env/envs/website.py
Original file line number Diff line number Diff line change
Expand Up @@ -44,7 +44,8 @@
from agent_env.env import legacy_protocol
from agent_env.env.envs._deployment import (
as_builtin, builtin_provider_for, close_deployed, close_replaced, deploy_refusal, deploy_through_provider, host_staging_refusal,
file_parts, legacy_load_file, load_by_signed_url, plugin_provider_like_a_builtin, provider_or_class, reset_server_data,
data_plane_headers, file_parts, legacy_load_file, load_by_signed_url, plugin_provider_like_a_builtin, provider_or_class,
reset_server_data,
staged_paths,
)
from agent_env.env.gateway import GatewayMode
Expand Down Expand Up @@ -321,9 +322,10 @@ async def load_environment_artifact(self, environment_artifact: EnvironmentArtif
try:
staged = {path: f"file://{await self._copy_artifact_into_container(file, paths[path])}"
for path, file in files.items()}
await protocol_v1.reset_data(base_url)
headers = data_plane_headers(self, base_url)
await protocol_v1.reset_data(base_url, headers=headers)
await protocol_v1.add_data(base_url, file_parts(environment_artifact, files, staged),
timeout=DATA_PLANE_LOAD_TIMEOUT_S)
timeout=DATA_PLANE_LOAD_TIMEOUT_S, headers=headers)
finally:
if folder is not None:
await self._remove_from_container(folder)
Expand Down
5 changes: 3 additions & 2 deletions src/agent_env/env/gateway/constants.py
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,9 @@ def sources(names: list[str]) -> str:
TOOL_DISABLE_ACTION = "disable"
TOOL_ENABLE_ACTION = "enable"
# The harness's routes that take the deploy's control token: the ones that change tool access, triggers and
# notifications. Every other route stays open for now, the clock's writes included: callers outside agent-env set the
# clock over plain HTTP and don't send the token yet.
# notifications. The gateway also takes it for the data plane and for an MCP server's own endpoint behind its proxy
# (Gateway._takes_control_token). Every other route stays open for now, the clock's writes included: callers outside
# agent-env set the clock over plain HTTP and don't send the token yet.
CONTROL_ROUTES = frozenset({
f"/tools/{TOOL_DISABLE_ACTION}", f"/tools/{TOOL_ENABLE_ACTION}",
"/triggers/register", "/triggers/remove", "/triggers/clear",
Expand Down
59 changes: 53 additions & 6 deletions src/agent_env/env/gateway/gateway.py
Original file line number Diff line number Diff line change
Expand Up @@ -86,6 +86,8 @@
called_tools,
fetch_child_card,
forward,
is_child_mcp_path,
reaches,
listed_url,
lowered,
operations,
Expand Down Expand Up @@ -178,7 +180,8 @@ def __init__(
self.rest_proxy_urls = rest_proxy_urls or {}
self._site_names = {site: lowered(names) for site, names in (site_names or {}).items()}
self._listed_by_name = frozenset(listed_by_name)
self._site_mcp_endpoints = site_mcp_endpoints(internal_mcp_servers, self.website_urls, self.rest_proxy_urls)
self._mcp_endpoints = mcp_endpoints(internal_mcp_servers, self.website_urls, self.rest_proxy_urls)
self._token_paths = token_paths(internal_mcp_servers, self.website_urls, self.rest_proxy_urls)
self._site_cards: dict[str, SiteCard] = {}
self._withheld = frozenset(name.strip().lower().encode() for name in provider_headers if name.strip())
self._browsers = BrowserRoutes(self.rest_proxy_urls, self.REST_PROXY_TIMEOUT, self._log_event,
Expand Down Expand Up @@ -545,8 +548,9 @@ def _asgi_app(self):
async def app(scope, receive, send):
if self._control_bearer and scope["type"] in ("http", "websocket"):
headers = scope.get("headers", ())
if scope["type"] == "http" and scope["path"] in CONTROL_ROUTES and not hmac.compare_digest(
if scope["type"] == "http" and self._takes_control_token(scope) and not hmac.compare_digest(
dict(headers).get(b"authorization", b""), self._control_bearer):
logger.warning("refused %s %s: it takes the env's control token", scope["method"], scope["path"])
response = self._json_response({"ok": False, "error": "this route takes the env's control token"}, 401)
await response(scope, receive, send)
return
Expand All @@ -569,6 +573,19 @@ async def app(scope, receive, send):

return app

def _takes_control_token(self, scope: dict) -> bool:
"""Whether a request takes the deploy's control token: a control route, the env's data plane, or one of
``token_paths`` behind /svc, by the path as routed or by the one the backing server receives (``reaches``),
after dot-segment normalisation. A site's /website route never reaches its data plane."""
path = scope["path"]
if path in CONTROL_ROUTES or is_child_mcp_path(path, RPC_PATH):
return True
prefix, _, rest = path.lstrip("/").partition("/")
service, _, rest = rest.partition("/")
guarded = self._token_paths.get(service, ()) if prefix == "svc" else ()
raw, base = scope.get("raw_path") or path.encode(), self.rest_proxy_urls.get(service, "")
return any(reaches(base, raw, path, rest, endpoint) for endpoint in guarded)

@asynccontextmanager
async def _session_lifespan(self, mcp: FastMCP):
"""Once per inbound MCP session: the session's key joins the caller, and a connect gets to heal a failed
Expand Down Expand Up @@ -784,12 +801,12 @@ async def _proxy_rest_request(self, request: Request, url_map: dict[str, str] |
if base_url is None:
return self._json_response({"error": f"Unknown service: {service_name}"}, 404)
role = self._request_role(request)
site_mcp = self._site_mcp_endpoints.get(service_name) if url_map is self.rest_proxy_urls else None
mcp_server = url_map is self.rest_proxy_urls and (service_name.startswith("mcp-") or site_mcp is not None)
mcp_endpoint = site_mcp or "mcp"
mcp_endpoint = self._mcp_endpoints.get(service_name) if url_map is self.rest_proxy_urls else None
mcp_server = mcp_endpoint is not None
mcp_endpoint = mcp_endpoint or "mcp"
if url_map is self.rest_proxy_urls and (cdp := await self._browsers.cdp_answer(request, base_url, role)) is not None:
return cdp
if mcp_server and request.method == "POST" and reaches_child_mcp(request, mcp_endpoint):
if mcp_server and request.method == "POST" and reaches_child_mcp(request, base_url, mcp_endpoint):
if (refusal := await self._refuse_disabled_calls(await request.body(), role)) is not None:
return refusal
if request.method in _SAFE_METHODS:
Expand Down Expand Up @@ -1741,6 +1758,36 @@ def site_mcp_endpoints(servers: list[InternalMCPServer], website_urls: dict[str,
return endpoints


def mcp_endpoints(servers: list[InternalMCPServer], website_urls: dict[str, str],
rest_proxy_urls: dict[str, str]) -> dict[str, str]:
"""The MCP endpoint, as a path under its /svc/<key>/ route, of each backing route that is an MCP server's: a site
that is an internal MCP server too (``site_mcp_endpoints``), and each ``mcp-`` route at the path its server's
``mcp_url`` gives, ``/mcp`` when none is under the route's address. Where the proxy stamps the role and applies the
tool rules, and where the control token is taken."""
endpoints = site_mcp_endpoints(servers, website_urls, rest_proxy_urls)
for key, base in rest_proxy_urls.items():
if key in endpoints or not key.startswith("mcp-"):
continue
name = route_environment_name(key, base, servers, website=False)
found = [resolved.route_path for server in servers if server.name == name
if (resolved := card_url(base, server.mcp_url)) is not None and resolved.own_server
and resolved.route_path is not None]
endpoints[key] = found[0] if found else "/mcp"
return endpoints


def token_paths(servers: list[InternalMCPServer], website_urls: dict[str, str],
rest_proxy_urls: dict[str, str]) -> dict[str, tuple[str, ...]]:
"""The paths under /svc/<key>/ that take the gateway's control token, by key: every backing server's data plane,
extensions included, and an MCP server's own endpoint (``mcp_endpoints``), which skips the gateway's trajectory and
triggers. A child env registered under its own name, a computer, takes its own token, so none of its paths are here."""
endpoints = mcp_endpoints(servers, website_urls, rest_proxy_urls)
return {key: (RPC_PATH, *((endpoints[key],) if key in endpoints else ()))
for key, base in rest_proxy_urls.items()
if key in website_urls or route_environment_name(key, base, servers, website=False) != key
or not any(server.name == key for server in servers)}


class CardURL(NamedTuple):
"""A URL a site's card names, as the site at an address serves it: its path and query; the path a request on the
site's route reaches it at, its path under the address's (None when it isn't under it); and whether it is on the
Expand Down
27 changes: 18 additions & 9 deletions src/agent_env/env/gateway/rest_proxy.py
Original file line number Diff line number Diff line change
Expand Up @@ -105,7 +105,7 @@ async def forward(request: Request, base_url: str, *, role: str, timeout: httpx.
return await _done(_json_response({"error": str(e)}, 400), on_done)
content = await request.body() # /svc and /website request bodies are small (JSON-RPC, forms)
headers = upstream_headers(request, role, withheld=withheld, site_names=site_names)
if mcp_server and request.method == "POST" and reaches_child_mcp(request, mcp_endpoint):
if mcp_server and request.method == "POST" and reaches_child_mcp(request, base_url, mcp_endpoint):
# The gateway is the trust boundary for identity: a child's proxied MCP endpoint stays reachable, but the
# role in its JSON-RPC `_meta` is the gateway's to write, like the header above.
content = stamp_jsonrpc_role(content, role)
Expand Down Expand Up @@ -274,17 +274,26 @@ def is_child_mcp_path(decoded_rest: str, endpoint: str = "mcp") -> bool:
return normalized == at or normalized.startswith(at + "/")


def reaches_child_mcp(request: HTTPConnection, endpoint: str = "mcp") -> bool:
"""Whether a /svc request reaches the backing server's MCP endpoint (:func:`is_child_mcp_path`), by the path as
routed here or by the one the server receives: the raw path forwarded, its dot segments removed by httpx and then
decoded, which differ when an encoded slash sits beside a dot segment (``public%2Fx/../mcp`` reaches ``/mcp``)."""
if is_child_mcp_path(request.path_params.get("path", ""), endpoint):
def reaches_child_mcp(request: HTTPConnection, base_url: str, endpoint: str = "mcp") -> bool:
"""Whether a /svc request reaches the MCP endpoint of the backing server at ``base_url`` (:func:`reaches`)."""
return reaches(base_url, request.scope["raw_path"], request.scope["path"], request.path_params.get("path", ""), endpoint)


def reaches(base_url: str, raw_path: bytes, decoded_path: str, decoded_rest: str, endpoint: str) -> bool:
"""Whether a /svc request whose routed remainder is ``decoded_rest`` reaches ``endpoint`` of the backing server at
``base_url`` (:func:`is_child_mcp_path`): by that remainder, or by the path the server receives, the base's path and
the raw remainder forwarded, its dot segments removed by httpx and then decoded. They differ when an encoded slash
sits beside a dot segment (``public%2Fx/../mcp`` reaches ``/mcp``) or a dot segment climbs into a base's path
(``../prefix/mcp`` reaches base ``/prefix``'s ``/mcp``). False for a request-target forward() refuses."""
if is_child_mcp_path(decoded_rest, endpoint):
return True
try:
sent = httpx.URL(upstream_url("http://child", request)).path
raw_rest = raw_remainder(raw_path, decoded_path, decoded_rest) if decoded_rest else b""
sent = httpx.URL(f"{base_url.rstrip('/')}/{raw_rest.decode('latin-1')}").path
base = httpx.URL(base_url).path.rstrip("/")
except (ValueError, httpx.InvalidURL):
return False # forward() refuses a request-target it can't build a URL for
return is_child_mcp_path(sent, endpoint)
return False
return is_child_mcp_path(sent, f"{base}/{endpoint.lstrip('/')}")


def stamp_jsonrpc_role(body: bytes, role: str) -> bytes:
Expand Down
Loading
Loading