feat(website): WebsiteEnvironment serves a site on the website/v1 contract, and a conformance check tests any server (FD-4683)

packages/agentenv-protocol/src/agentenv_protocol/website/__init__.py

@@ -0,0 +1,30 @@
+"""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."""
+
+from __future__ import annotations
+
+from .clock import CLOCK_EXTENSION_URI, UNIVERSE_NOW_HEADER, UniverseClock
+from .environment import (
+    DEFAULT_HEALTH_PATH,
+    SESSION_PATH,
+    STATE_PATH,
+    WEBSITE_EXTENSION_URI,
+    WebsiteDeclaration,
+    WebsiteEnvironment,
+    ready_check,
+    website,
+)
+from .errors import ApiError, BadRequest, Conflict, Forbidden, NotFound, Unauthorized
+from .routes import ROLE_KEY_ENV, ROLE_KEY_HEADER, ApiContext, ApiRoute, api, reserved_path
+from .session import SESSION_COOKIE, SessionSigner
+from .store import Collections
+
+__all__ = [
+    "WebsiteEnvironment", "WebsiteDeclaration", "website", "api", "ApiContext", "ApiRoute", "ready_check",
+    "ApiError", "BadRequest", "Unauthorized", "Forbidden", "NotFound", "Conflict",
+    "Collections", "UniverseClock", "SessionSigner", "reserved_path",
+    "WEBSITE_EXTENSION_URI", "CLOCK_EXTENSION_URI", "UNIVERSE_NOW_HEADER", "DEFAULT_HEALTH_PATH", "SESSION_PATH",
+    "STATE_PATH", "SESSION_COOKIE", "ROLE_KEY_ENV", "ROLE_KEY_HEADER",
+]

packages/agentenv-protocol/src/agentenv_protocol/website/clock.py

@@ -0,0 +1,113 @@
+"""The universe's clock as a site reads it: ``clock/v1``'s ``sync_time`` hands the server the gateway's ``/clock/time``
+URL, as it hands it to MCP servers, and the site's time then follows that clock's ``{"virtual_time": <RFC3339>}``,
+read at most once a second and extrapolated between reads. The rate it extrapolates at is one two successive intervals
+between reads agreed on, so a clock set or advanced between two reads is taken for a jump, not a speed; until two agree
+it is real time's. An unsynced site reads wall time. Every answer of a site carries the time it answered at as ``X-Universe-Now``,
+RFC3339 in UTC. ``sync_time`` may also name the universe's time zone, an IANA name, which the clock keeps for the site
+to show local times in; the time itself stays UTC."""
+from __future__ import annotations
+
+import asyncio
+import datetime
+import json
+import logging
+import time
+
+import httpx
+
+logger = logging.getLogger(__name__)
+
+CLOCK_EXTENSION_URI = "urn:agentenv:clock/v1"
+UNIVERSE_NOW_HEADER = "X-Universe-Now"
+REFRESH_S = 1.0
+READ_TIMEOUT_S = 5.0
+
+
+def iso(moment: datetime.datetime) -> str:
+    return moment.astimezone(datetime.timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
+
+
+def parse_time(value: str) -> datetime.datetime:
+    moment = datetime.datetime.fromisoformat(value.replace("Z", "+00:00"))
+    return moment if moment.tzinfo else moment.replace(tzinfo=datetime.timezone.utc)
+
+
+class UniverseClock:
+    """The time a site answers with: wall time until ``sync`` names a gateway clock, that clock's after."""
+
+    def __init__(self) -> None:
+        self.url: str | None = None
+        self.timezone: str | None = None
+        self._virtual: datetime.datetime | None = None
+        self._read_at = 0.0
+        self._tried_at = 0.0
+        self._rate = 1.0
+        self._measured: float | None = None
+        self._lock: asyncio.Lock | None = None
+
+    @property
+    def synced(self) -> bool:
+        return self._virtual is not None
+
+    def now(self) -> datetime.datetime:
+        if self._virtual is None:
+            return datetime.datetime.now(datetime.timezone.utc)
+        return self._virtual + datetime.timedelta(seconds=(time.monotonic() - self._read_at) * self._rate)
+
+    async def sync(self, url: str, timezone: str | None = None) -> datetime.datetime:
+        """Follow the clock at ``url`` from now on, in ``timezone`` (none when the sync names none); raises when it
+        can't be read, keeping the clock and zone it followed. It waits for a refresh reading the clock it followed,
+        so that read never lands on the new clock."""
+        async with self._reading():
+            virtual = await _read(url)
+            self.url, self._virtual, self._rate, self._measured = url, virtual, 1.0, None
+            self.timezone = timezone
+            self._read_at = self._tried_at = time.monotonic()
+            return virtual
+
+    async def refresh(self) -> None:
+        """Read the synced clock again when the last read is a second old; a failed read keeps extrapolating."""
+        if self.url is None or time.monotonic() - self._tried_at < REFRESH_S:
+            return
+        async with self._reading():
+            started = time.monotonic()
+            if started - self._tried_at < REFRESH_S:
+                return
+            self._tried_at = started
+            try:
+                virtual = await _read(self.url)
+            except Exception as e:
+                logger.debug("reading the universe's clock at %s failed: %r", self.url, e)
+                return
+            read_at = time.monotonic()
+            if self._virtual is not None and read_at > self._read_at:
+                measured = max(0.0, (virtual - self._virtual).total_seconds() / (read_at - self._read_at))
+                if self._measured is not None and abs(measured - self._measured) <= 0.1 * max(measured, self._measured, 1.0):
+                    self._rate = measured
+                self._measured = measured
+            self._virtual, self._read_at = virtual, read_at
+
+    def _reading(self) -> asyncio.Lock:
+        """The lock a sync and a refresh each read the clock under."""
+        self._lock = self._lock or asyncio.Lock()
+        return self._lock
+
+
+async def _read(url: str) -> datetime.datetime:
+    async with httpx.AsyncClient() as client:
+        response = await client.get(url, timeout=READ_TIMEOUT_S)
+        response.raise_for_status()
+        return parse_time(response.json()["virtual_time"])
+
+
+def clock_patch_script(now: datetime.datetime) -> bytes:
+    """An inline script that shifts the page's ``Date`` to the universe's time ``now``, and follows the
+    ``X-Universe-Now`` header of every ``fetch`` the page makes after. The ``Date`` it puts in place answers called,
+    with the time's string, as constructed, and keeps ``Date.parse``, ``Date.UTC`` and ``instanceof Date``."""
+    return ("<script>(function(){var D=Date,o=%s-D.now();function n(){return D.now()+o}"
+            "function U(){if(!new.target)return new D(n()).toString();"
+            "return Reflect.construct(D,arguments.length?[].slice.call(arguments):[n()],new.target)}"
+            "Object.setPrototypeOf(U,D);U.prototype=D.prototype;D.prototype.constructor=U;U.now=n;U.parse=D.parse;"
+            "U.UTC=D.UTC;window.Date=U;var f=window.fetch;if(f)window.fetch=function(){return f.apply(this,arguments)"
+            ".then(function(r){var t=D.parse(r.headers.get(%s)||'');if(!isNaN(t))o=t-D.now();return r})}})();"
+            "</script>" % (int(now.timestamp() * 1000), json.dumps(UNIVERSE_NOW_HEADER))).encode()