Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
47 changes: 47 additions & 0 deletions packages/agentenv-protocol/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -544,6 +544,53 @@ class GitHub(WebsiteEnvironment):
- **The run:** a run that deploys a live site is marked live. The deploy record says `live`, and the run's metadata lists
its live sites with `reproducible: false`, because the real site may change between runs.

A third-party site is an app someone else wrote, such as a web store, that serves its own pages, wrapped so agentenv
deploys it like any site. `ForwardingSite` runs in the app's container beside it: it answers the card, the data plane
and `website/v1` itself, and forwards every other request to the app.

```python
from agentenv_protocol.website import ForwardingSite, session_state, website


@website(domains=["store.localhost"], builtin_routes=False, clock="real", ready_timeout_s=600)
class Store(ForwardingSite):
upstream = "http://127.0.0.1:80" # the app, in the same container
ready_path = "/admin" # ready once the app answers this below 500
sign_in_headers = ("X-Auto-Login",) # only the site's own calls send these; logged with values removed

@session_state
async def signed_in(self, user: str | None) -> dict:
answer = await self.ask_app("/admin", headers={"X-Auto-Login": "..."})
... # return the cookies the app answered with
```

- **Forwarding:** a request goes to the app as it came: its method, the site's own path with its encoding intact (an
escaped `/` stays escaped, and a forwarded prefix is taken off), its query, the `Host` the browser named and its
body, streamed, with no header or cookie of the forwarder's own. The hop-by-hop headers and `sign_in_headers` stay
behind. The answer comes back as the app gave it, streamed and still encoded, a redirect unfollowed, but a cookie
the app ties to one of the site's names (`Domain`) comes back the host's alone, as agentenv sets a sign-in's
cookies, so a sign-in replaces the app's session cookie rather than setting a second one beside it. An app not
answering is a 502 (`upstream_unavailable`). It forwards HTTP alone, and refuses a WebSocket with close code 1011.
- **`builtin_routes=False`** serves none of agentenv's own site routes, so `/api/session` reaches the app too, and the
card names no `session_path` or `session_cookie`. Any `WebsiteEnvironment` may set it.
- **`clock="real"`** declares a site that keeps real time, as an app that reads the system clock does: its card serves
no `clock/v1`, its `website/v1` params say `clock: "real"` (`WEBSITE_CLOCK_PARAM`), its answers carry no
`X-Universe-Now`, and `sync_env_clock` passes it over. The conformance check skips its two clock checks.
`@website` refuses `clock_patch` with it, since there's no universe time to put in a page.
- **Its data plane:** the app keeps its own data, so the site serves `data/get` alone, which exports nothing. It takes
no load and can't reset: agentenv's reset passes over a card serving no `data/reset`, and the conformance check
passes a card serving `data/get` alone once `data/get` answers.
- **Its session:** `@session_state` signs the browser in with whatever cookies the app sets, for example from one
server-side request carrying a sign-in header, which `sign_in_headers` then keeps the browser from sending. The
card names them too (`WEBSITE_SIGN_IN_HEADERS_PARAM`), so should a browser's request carry one, the browser's
network log, and so `network.har`, keeps it with its value taken out.
- **Its own calls:** `ask_app(path, method=..., headers=..., content=...)` asks the app as the site does, under its
first name as `Host`, through the forwarder's client, which keeps no cookie and follows no redirect. Its session
and ready checks use it, as `ForwardingSite`'s own ready check does.
- **Its names:** an app with a fixed base URL answers any other `Host` with a redirect to its own name. A browser
reaches it by that name alone, the site proxy naming it, and the conformance check's `any_host` passes `/` redirecting
to one of the card's `domains` as it does `/` serving HTML.

## Computer drivers

A computer driver is what runs inside a computer an agent uses through screenshots and input. Write
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -21,14 +21,12 @@
from websockets.asyncio.client import ClientConnection

from ..agent_env_environment import _error_response
from ..passthrough import passed_on
from .errors import DeliveryFailed
from .served import TOKEN_HEADER, served

#: The methods the route forwards.
METHODS = ["GET", "HEAD", "POST", "PUT", "PATCH", "DELETE", "OPTIONS"]
#: The headers that belong to one connection, which a proxy doesn't pass on.
HOP_HEADERS = frozenset({"connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection",
"te", "trailer", "transfer-encoding", "upgrade"})
#: The address a request reached the driver at, which the driver sets for the app in place of any the caller sent.
FORWARDED = ("x-forwarded-host", "x-forwarded-proto", "x-forwarded-prefix")
#: A WebSocket close code that means the connection ended without one, which a close can't send on.
Expand All @@ -45,16 +43,6 @@
FORWARDER_LOGGER = "httpx"


def passed_on(headers: Iterable[tuple[str, str]], *dropped: str) -> list[tuple[str, str]]:
"""``headers`` as a proxy passes them on: without the hop-by-hop ones, those a ``Connection`` header names, and
``dropped``."""
headers = list(headers)
named = {token.strip().lower() for name, value in headers if name.lower() == "connection"
for token in value.split(",")}
skipped = HOP_HEADERS | named | set(dropped)
return [(name, value) for name, value in headers if name.lower() not in skipped]


def to_app(headers: Iterable[tuple[str, str]], host: str, scheme: str, prefix: str) -> list[tuple[str, str]]:
"""A caller's headers as the app gets them: passed on without the control token's ``Authorization`` or any address
the caller forwarded, nor any app token, which the driver sets itself where the app takes one, and with the
Expand Down
19 changes: 19 additions & 0 deletions packages/agentenv-protocol/src/agentenv_protocol/passthrough.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
"""What a proxy passes on of the headers it relays, shared by the driver's ``/svc/<name>/`` route and a website that
forwards to an app beside it."""
from __future__ import annotations

from collections.abc import Iterable

#: The headers that belong to one connection, which a proxy doesn't pass on.
HOP_HEADERS = frozenset({"connection", "keep-alive", "proxy-authenticate", "proxy-authorization", "proxy-connection",
"te", "trailer", "transfer-encoding", "upgrade"})


def passed_on(headers: Iterable[tuple[str, str]], *dropped: str) -> list[tuple[str, str]]:
"""``headers`` as a proxy passes them on: without the hop-by-hop ones, those a ``Connection`` header names, and
``dropped``, each matched without regard to case."""
headers = list(headers)
named = {token.strip().lower() for name, value in headers if name.lower() == "connection"
for token in value.split(",")}
skipped = HOP_HEADERS | named | {name.lower() for name in dropped}
return [(name, value) for name, value in headers if name.lower() not in skipped]
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
"""The website SDK: a site's server, meeting ``urn:agentenv:website/v1``. Subclass WebsiteEnvironment, declare the
site with ``@website(domains=[...], static="dist/")``, mark its API with ``@api.get/post/put/patch/delete(path)``, and
``serve()`` it; it needs only the plain package, and uvicorn to serve. The class is optional: a server in any language
that meets the contract works, which ``python -m agentenv_protocol.website.conformance <url>`` checks. Whether a site
is ready is its ``WebsiteReadiness`` answer to ``ready``, which ``website_readiness`` reads of one site and
``serve()`` it, or wrap an app that serves its own pages with ``ForwardingSite``; it needs only the plain package, and
uvicorn to serve. The class is optional: a server in any language that meets the contract works, which ``python -m
agentenv_protocol.website.conformance <url>`` checks. Whether a site is ready is its ``WebsiteReadiness`` answer to ``ready``, which ``website_readiness`` reads of one site and
``env_readiness`` of every site of an env. What a task left a site with is its data plane's ``data/get``."""

from __future__ import annotations
Expand All @@ -19,15 +19,20 @@
website,
)
from .errors import ApiError, BadRequest, Conflict, Forbidden, NotFound, Unauthorized
from .forwarding import ForwardingSite
from .readiness import (
DEFAULT_HEALTH_PATH,
READY_TIMEOUT_S,
REAL_CLOCK,
SITE_READY_TIMEOUT_S,
UNIVERSE_CLOCK,
WEBSITE_ALLOW_HOSTS_PARAM,
WEBSITE_BROWSE_URL_PARAM,
WEBSITE_CLOCK_PARAM,
WEBSITE_EXTENSION_URI,
WEBSITE_LIVE_PARAM,
WEBSITE_READY_OP,
WEBSITE_SIGN_IN_HEADERS_PARAM,
WebsiteReadiness,
env_readiness,
website_readiness,
Expand All @@ -38,9 +43,10 @@
__all__ = [
"WebsiteEnvironment", "WebsiteDeclaration", "website", "api", "ApiContext", "ApiRoute", "ready_check", "session_state", "host_problem",
"ApiError", "BadRequest", "Unauthorized", "Forbidden", "NotFound", "Conflict",
"UniverseClock", "ClockUnavailable", "SessionSigner", "reserved_path",
"UniverseClock", "ClockUnavailable", "SessionSigner", "reserved_path", "ForwardingSite",
"WEBSITE_EXTENSION_URI", "CLOCK_EXTENSION_URI", "UNIVERSE_NOW_HEADER", "DEFAULT_HEALTH_PATH", "SESSION_PATH",
"SESSION_COOKIE", "SESSION_SECRET_ENV", "ROLE_KEY_ENV", "ROLE_KEY_HEADER",
"WEBSITE_READY_OP", "WEBSITE_BROWSE_URL_PARAM", "WEBSITE_LIVE_PARAM", "WEBSITE_ALLOW_HOSTS_PARAM", "WEBSITE_SETTINGS_ENV", "READY_TIMEOUT_S", "SITE_READY_TIMEOUT_S", "WebsiteReadiness",
"WEBSITE_READY_OP", "WEBSITE_BROWSE_URL_PARAM", "WEBSITE_LIVE_PARAM", "WEBSITE_ALLOW_HOSTS_PARAM", "WEBSITE_CLOCK_PARAM",
"WEBSITE_SIGN_IN_HEADERS_PARAM", "UNIVERSE_CLOCK", "REAL_CLOCK", "WEBSITE_SETTINGS_ENV", "READY_TIMEOUT_S", "SITE_READY_TIMEOUT_S", "WebsiteReadiness",
"website_readiness", "env_readiness",
]
Original file line number Diff line number Diff line change
Expand Up @@ -3,16 +3,19 @@
``--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
card declaring the site's domains, readiness and routes; ``/`` serving HTML under a made-up host, or redirecting to
one of the site's own names; 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, or, for a card serving ``data/get`` alone, a site whose app keeps its own
data and so takes no load and can't reset, which answers it; 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 (both skipped for a site whose
``website/v1`` params declare ``clock: "real"``, a third-party app that keeps real time), 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``.
Expand All @@ -36,16 +39,20 @@
import uuid
from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
from typing import Callable, Iterator, Literal
from urllib.parse import urlsplit

import httpx
from pydantic import ValidationError

from ..client import find_extension, find_extension_method
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
from .readiness import (DEFAULT_HEALTH_PATH, REAL_CLOCK, WEBSITE_CLOCK_PARAM, WEBSITE_EXTENSION_URI, WEBSITE_READY_OP,
WebsiteReadiness, names_host)

Status = Literal["passed", "failed", "skipped", "warned"]
#: The checks of a site's clock, which a card declaring a real clock skips.
CLOCK_CHECKS = ("universe_now", "clock")
CLOCK_START = datetime.datetime(2031, 5, 6, 7, 8, 9, tzinfo=datetime.timezone.utc)
CLOCK_SLACK_S = 120
MCP_PROTOCOL_VERSION = "2025-06-18"
Expand Down Expand Up @@ -114,14 +121,21 @@ def run(self) -> list[Result]:
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
# (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),
steps = (("card", True, lambda: self._card(response, card, site)), ("any_host", True, lambda: self._any_host(site)),
("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)
real_clock = site.get(WEBSITE_CLOCK_PARAM) == REAL_CLOCK

def outcome(name: str, step: Callable[[], tuple[Status, str]]) -> tuple[Status, str]:
if real_clock and name in CLOCK_CHECKS:
return "skipped", "the card declares a real clock, which nothing moves"
return _outcome(step)

outcomes = {name: outcome(name, step) for name, _required, step in steps if name != "universe_now"}
outcomes["universe_now"] = outcome("universe_now", self._universe_now)
results = []
for name, required, _step in steps:
status, detail = outcomes[name]
Expand All @@ -145,13 +159,20 @@ def _card(self, response: httpx.Response, card: dict, site: dict) -> tuple[Statu
problems.append("its params' routes aren't a list of {method, path, name}")
return ("failed" if problems else "passed"), "; ".join(problems)

def _any_host(self) -> tuple[Status, str]:
def _any_host(self, site: dict) -> tuple[Status, str]:
"""``/`` under a made-up Host serves HTML, or redirects to one of the site's own names: an app with a fixed
base URL, which a browser reaches only by its name."""
host = f"conformance-{uuid.uuid4().hex[:8]}.invalid"
response = self.get("/", headers={"Host": host})
response = self.get("/", headers={"Host": host}, follow_redirects=False)
kind = response.headers.get("content-type", "")
if response.status_code == 200 and kind.startswith("text/html"):
return "passed", f"/ served HTML for Host {host}"
return "failed", f"/ for Host {host} answered {response.status_code} {kind or 'without a content type'}"
to = (urlsplit(response.headers.get("location", "")).hostname or "") if response.is_redirect else ""
domains = site.get("domains") if isinstance(site.get("domains"), list) else []
if to and any(isinstance(domain, str) and names_host(domain.lower(), to) for domain in domains):
return "passed", f"/ for Host {host} redirected to the site's own name {to}"
return "failed", (f"/ for Host {host} answered {response.status_code} {kind or 'without a content type'}"
+ (f", redirecting to {to}, not one of the site's names" if to else ""))

def _health(self, card: dict, health: str) -> tuple[Status, str]:
ready = find_extension_method(card, WEBSITE_EXTENSION_URI, WEBSITE_READY_OP)
Expand Down Expand Up @@ -208,11 +229,15 @@ def _data_plane(self, card: dict) -> tuple[Status, str]:
operations = (card.get("capabilities") or {}).get("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:
get_alone = set(missing) == {METHOD_RESET, METHOD_ADD}
if missing and not get_alone:
return "failed", f"the card's operations lack {', '.join(missing)}"
url = card.get("url")
self.rpc_url = self._url(url if isinstance(url, str) and url else RPC_PATH)
exported = self._rpc(METHOD_GET).get("parts") or []
if get_alone:
return "passed", (f"the card serves {METHOD_GET} alone, which answered with {len(exported)} part(s): a site "
"whose app keeps its own data, which takes no load and can't reset")
self._rpc(METHOD_RESET)
added_back = False
try:
Expand Down
Loading
Loading