agentenv-framework-protocol 0.1.456__tar.gz → 0.1.459__tar.gz

{agentenv_framework_protocol-0.1.456 → agentenv_framework_protocol-0.1.459}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.456
+Version: 0.1.459
 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
@@ -490,6 +490,37 @@ async with ToolSession(mcp_url=mcp_url, role="alice@example.com") as session:
 - **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.
 
+## Website readiness
+
+`agentenv_protocol.website` is the one definition of whether a website env is healthy. A site's card advertises
+`urn:agentenv:website/v1`'s `ready` (`WEBSITE_READY_OP`), a GET answering a `WebsiteReadiness`: `ready`, a boolean,
+`problems`, what keeps it from being ready, and optionally `waited_s` since its server started and the `timeout_s` it
+may take (`SITE_READY_TIMEOUT_S` when it says nothing), which is how long a deploy waits for it. A
+`WebsiteEnvironment` answers from its `@ready_check` methods, run at once, each within `CHECK_TIMEOUT_S` and a plain
+`def` in a worker thread, and from `@website(ready_timeout_s=...)`; it serves no separate health path. The model is
+strict about `ready` and `problems` (`"yes"` is no `ready`) and ignores fields it doesn't know, so a reader keeps
+reading a newer site. A server whose card has no `ready` is still read at its health path (`DEFAULT_HEALTH_PATH`
+unless it names one), which is deprecated. Everything that judges a site reads it through these helpers: agent-env's deploy,
+`DeployedEnv.readiness()`, and the conformance checker's `health`, which fails an answer that isn't a
+`WebsiteReadiness`.
+
+```python
+from agentenv_protocol.website import env_readiness, website_readiness
+
+site = await website_readiness(base_url, card)   # WebsiteReadiness, or None for a card without ready
+env = await env_readiness(gateway_url, env_card)  # WebsiteReadiness of every site of the env
+print(env.ready, env.problems)                    # False ['shop: seeded']
+```
+
+- **One site:** `website_readiness(base_url, card, *, timeout=READY_TIMEOUT_S, headers=None)` asks the site as its card
+  advertises `ready`. It raises httpx's error when the site can't be reached, `ExtensionCallError` for a non-2xx
+  answer and `ValueError` (pydantic's `ValidationError`) for an answer that isn't a `WebsiteReadiness`.
+- **An env:** `env_readiness(base_url, card, ...)` asks, at once, the card itself when it advertises `ready` (a single
+  site's card), and every child under a composed card's `children_environments` that does, its endpoints rooted at
+  `base_url` as a gateway's are. A child's problems are prefixed with its name (`shop: seeded`); one that can't be
+  asked, or answers no `WebsiteReadiness`, is a problem itself. A card or child without `ready`, an MCP server's or an
+  older site's, isn't counted, so an env with no site serving it is ready with no problems.
+
 ## Computer drivers
 
 A computer driver is what runs inside a computer an agent uses through screenshots and input. Write

{agentenv_framework_protocol-0.1.456 → agentenv_framework_protocol-0.1.459}/README.md

@@ -431,6 +431,37 @@ async with ToolSession(mcp_url=mcp_url, role="alice@example.com") as session:
 - **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.
 
+## Website readiness
+
+`agentenv_protocol.website` is the one definition of whether a website env is healthy. A site's card advertises
+`urn:agentenv:website/v1`'s `ready` (`WEBSITE_READY_OP`), a GET answering a `WebsiteReadiness`: `ready`, a boolean,
+`problems`, what keeps it from being ready, and optionally `waited_s` since its server started and the `timeout_s` it
+may take (`SITE_READY_TIMEOUT_S` when it says nothing), which is how long a deploy waits for it. A
+`WebsiteEnvironment` answers from its `@ready_check` methods, run at once, each within `CHECK_TIMEOUT_S` and a plain
+`def` in a worker thread, and from `@website(ready_timeout_s=...)`; it serves no separate health path. The model is
+strict about `ready` and `problems` (`"yes"` is no `ready`) and ignores fields it doesn't know, so a reader keeps
+reading a newer site. A server whose card has no `ready` is still read at its health path (`DEFAULT_HEALTH_PATH`
+unless it names one), which is deprecated. Everything that judges a site reads it through these helpers: agent-env's deploy,
+`DeployedEnv.readiness()`, and the conformance checker's `health`, which fails an answer that isn't a
+`WebsiteReadiness`.
+
+```python
+from agentenv_protocol.website import env_readiness, website_readiness
+
+site = await website_readiness(base_url, card)   # WebsiteReadiness, or None for a card without ready
+env = await env_readiness(gateway_url, env_card)  # WebsiteReadiness of every site of the env
+print(env.ready, env.problems)                    # False ['shop: seeded']
+```
+
+- **One site:** `website_readiness(base_url, card, *, timeout=READY_TIMEOUT_S, headers=None)` asks the site as its card
+  advertises `ready`. It raises httpx's error when the site can't be reached, `ExtensionCallError` for a non-2xx
+  answer and `ValueError` (pydantic's `ValidationError`) for an answer that isn't a `WebsiteReadiness`.
+- **An env:** `env_readiness(base_url, card, ...)` asks, at once, the card itself when it advertises `ready` (a single
+  site's card), and every child under a composed card's `children_environments` that does, its endpoints rooted at
+  `base_url` as a gateway's are. A child's problems are prefixed with its name (`shop: seeded`); one that can't be
+  asked, or answers no `WebsiteReadiness`, is a problem itself. A card or child without `ready`, an MCP server's or an
+  older site's, isn't counted, so an env with no site serving it is ready with no problems.
+
 ## Computer drivers
 
 A computer driver is what runs inside a computer an agent uses through screenshots and input. Write

{agentenv_framework_protocol-0.1.456 → agentenv_framework_protocol-0.1.459}/pyproject.toml

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

{agentenv_framework_protocol-0.1.456 → agentenv_framework_protocol-0.1.459}/src/agentenv_protocol/computer/recording.py

@@ -52,6 +52,8 @@ FAILING_S = 60.0
 GAP_S = 2.0
 #: How long a stream that stopped or failed waits before it is started again.
 RETRY_S = 1.0
+#: How long a recording's start waits for its first frame, so a recording a start answered for is recording.
+FIRST_FRAME_S = 5.0
 #: How often free disk is checked while frames arrive.
 DISK_CHECK_S = 5.0
 KEEP_ENDED = 64
@@ -127,8 +129,9 @@ def recording_params(recording: Recording, streams: bool) -> dict:
 
 
 class Recordings:
-    """The recordings of one driver: started by request id, open ones counted against ``max_concurrent``, ended
-    ones kept with their manifests so a repeated ``end`` answers the same."""
+    """The recordings of one driver: started by request id, each start answering once its recording is recording, open
+    ones counted against ``max_concurrent``, ended ones kept with their manifests so a repeated ``end`` answers the
+    same."""
 
     def __init__(self, runtime: ComputerRuntime) -> None:
         self.runtime = runtime
@@ -144,7 +147,9 @@ class Recordings:
             raise InvalidArgument("request_id is a non-empty string")
         async with self._lock:
             if request_id in self.started:
-                return self.started[request_id]
+                answer = self.started[request_id]
+                await self._live(self.running.get(answer["recording_id"]))
+                return answer
             hints, grant = self._hints(features, scope, window, fps, max_edge, cursor, upload)
             stopped = [rid for rid, r in self.running.items() if r.done]
             for rid in stopped[:max(0, len(stopped) - KEEP_ENDED)]:  # stopped by itself and never ended
@@ -164,8 +169,16 @@ class Recordings:
             self.started[request_id] = answer
             while len(self.started) > KEEP_STARTED:
                 self.started.popitem(last=False)
+            await self._live(recording)
             return answer
 
+    @staticmethod
+    async def _live(recording: Optional[_Recording]) -> None:
+        """Wait up to FIRST_FRAME_S for ``recording``, one still running, to have its first frame."""
+        if recording is not None:
+            with contextlib.suppress(TimeoutError):
+                await asyncio.wait_for(recording.live.wait(), FIRST_FRAME_S)
+
     async def end(self, recording_id: str, upload: Optional[dict], reason: str) -> dict:
         if reason not in REASONS:
             raise InvalidArgument(f"reason is one of {list(REASONS)}, got {reason!r}")
@@ -219,6 +232,7 @@ class _Recording:
         self.ended_by: Optional[str] = None
         self.error: Optional[str] = None
         self.done = False
+        self.live = asyncio.Event()
         self.task: Optional[asyncio.Task] = None
         self.timer: Optional[asyncio.TimerHandle] = None
         self.released: Optional[asyncio.Future] = None
@@ -228,7 +242,11 @@ class _Recording:
         self._last_disk_check = 0.0
 
     async def run(self) -> None:
+        """Frames or segments from the source, recorded until the recording ends; ``live`` once it's recording: a
+        stream from its start, the fallback's polling from its first frame, which a busy computer is slow to take."""
         failing_since: Optional[float] = None
+        if self.streams:
+            self.live.set()
         try:
             while True:
                 try:
@@ -255,6 +273,7 @@ class _Recording:
                 await self._close()
             finally:
                 self.done = True
+                self.live.set()
                 self.released = asyncio.ensure_future(self._release())
 
     def expire(self) -> None:
@@ -315,6 +334,7 @@ class _Recording:
             path = self.hints.directory / f"{len(self.segments):04d}.mp4"
             self.encoder = await self._in_thread(_Encoder, path, frame.width, frame.height, self.hints.fps, at)
         await self._in_thread(self.encoder.add, frame, at)
+        self.live.set()
         self._check_disk()
 
     async def _add_segment(self, item: RecordedSegment) -> None:

agentenv_framework_protocol-0.1.459/src/agentenv_protocol/website/__init__.py

@@ -0,0 +1,41 @@
+"""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
+``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
+
+from .clock import CLOCK_EXTENSION_URI, UNIVERSE_NOW_HEADER, ClockUnavailable, UniverseClock
+from .environment import (
+    SESSION_PATH,
+    WebsiteDeclaration,
+    WebsiteEnvironment,
+    host_problem,
+    ready_check,
+    website,
+)
+from .errors import ApiError, BadRequest, Conflict, Forbidden, NotFound, Unauthorized
+from .readiness import (
+    DEFAULT_HEALTH_PATH,
+    READY_TIMEOUT_S,
+    SITE_READY_TIMEOUT_S,
+    WEBSITE_EXTENSION_URI,
+    WEBSITE_READY_OP,
+    WebsiteReadiness,
+    env_readiness,
+    website_readiness,
+)
+from .routes import ROLE_KEY_ENV, ROLE_KEY_HEADER, ApiContext, ApiRoute, api, reserved_path
+from .session import SESSION_COOKIE, SESSION_SECRET_ENV, SessionSigner
+
+__all__ = [
+    "WebsiteEnvironment", "WebsiteDeclaration", "website", "api", "ApiContext", "ApiRoute", "ready_check", "host_problem",
+    "ApiError", "BadRequest", "Unauthorized", "Forbidden", "NotFound", "Conflict",
+    "UniverseClock", "ClockUnavailable", "SessionSigner", "reserved_path",
+    "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", "READY_TIMEOUT_S", "SITE_READY_TIMEOUT_S", "WebsiteReadiness",
+    "website_readiness", "env_readiness",
+]

agentenv_framework_protocol-0.1.459/src/agentenv_protocol/website/clock.py

@@ -0,0 +1,142 @@
+"""The universe's clock as a site reads it, the way MCP servers read it: ``clock/v1``'s ``sync_time`` hands the server
+the gateway's ``/clock/time`` URL, and each request then reads that clock's ``{"virtual_time": <RFC3339>}`` once,
+the one instant everything the request does reads (``now()``) and its answer carries as ``X-Universe-Now``, RFC3339 in
+UTC. Requests that arrive while a read is in flight share it, over one pooled connection, so a burst costs the gateway
+one read. An unsynced site reads wall time, and so does a synced one whose gateway clock isn't armed (404); one whose clock
+can't be read raises ``ClockUnavailable``. ``sync_time`` with an empty URL goes back to wall time. ``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 contextvars
+import datetime
+import json
+import re
+
+import httpx
+
+CLOCK_EXTENSION_URI = "urn:agentenv:clock/v1"
+UNIVERSE_NOW_HEADER = "X-Universe-Now"
+READ_TIMEOUT = httpx.Timeout(connect=0.5, read=1.0, write=1.0, pool=0.5)
+READ_ATTEMPTS = 2
+
+_FRACTION = re.compile(r"(\.\d+)(?=[+-]\d\d:?\d\d$|Z$|$)")
+_request_now: contextvars.ContextVar[datetime.datetime | None] = contextvars.ContextVar("universe_now", default=None)
+
+
+class ClockUnavailable(Exception):
+    """The synced clock couldn't be read: unreachable, a 5xx after a retry, or an answer that isn't a time."""
+
+
+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:
+    """An RFC3339 time, its fraction of a second of any length (Python 3.10 parses only 3 or 6 digits)."""
+    value = _FRACTION.sub(lambda m: m.group(1)[:7].ljust(7, "0"), value.replace("Z", "+00:00"))
+    moment = datetime.datetime.fromisoformat(value)
+    return moment if moment.tzinfo else moment.replace(tzinfo=datetime.timezone.utc)
+
+
+def _wall() -> datetime.datetime:
+    return datetime.datetime.now(datetime.timezone.utc)
+
+
+class UniverseClock:
+    """The time a site answers with: wall time until ``sync`` names a gateway clock, that clock's, read per request,
+    after."""
+
+    def __init__(self) -> None:
+        self.url: str | None = None
+        self.timezone: str | None = None
+        self._last: datetime.datetime | None = None
+        self._loop: asyncio.AbstractEventLoop | None = None
+        self._client: httpx.AsyncClient | None = None
+        self._reading: tuple[str, asyncio.Future] | None = None
+
+    @property
+    def synced(self) -> bool:
+        return self.url is not None
+
+    def now(self) -> datetime.datetime:
+        """The instant the request being answered read, else the last one read, else wall time."""
+        return _request_now.get() or self._last or _wall()
+
+    async def read(self) -> datetime.datetime:
+        """The universe's time now: the synced clock's, wall time when none is synced or it isn't armed; raises
+        ``ClockUnavailable`` when it can't be read."""
+        if self.url is None:
+            return _wall()
+        self._last = await self._shared_read(self.url) or _wall()
+        return self._last
+
+    def answering_at(self, moment: datetime.datetime) -> contextvars.Token:
+        """Make ``moment`` what ``now()`` reads while the current request is answered."""
+        return _request_now.set(moment)
+
+    def answered(self, token: contextvars.Token) -> None:
+        _request_now.reset(token)
+
+    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), or wall time again
+        for an empty ``url``; raises ``ClockUnavailable`` when the clock can't be read, keeping the clock and zone it
+        followed."""
+        if not url:
+            self.url, self.timezone, self._last, self._reading = None, None, None, None
+            return _wall()
+        virtual = await _read(self._pooled(), url) or _wall()
+        self.url, self.timezone, self._last, self._reading = url, timezone, virtual, None
+        return virtual
+
+    async def _shared_read(self, url: str) -> datetime.datetime | None:
+        """The clock at ``url``'s time, from the read already in flight for it when there is one, else a new one."""
+        client = self._pooled()
+        if self._reading is None or self._reading[0] != url or self._reading[1].done():
+            reading = asyncio.ensure_future(_read(client, url))
+            reading.add_done_callback(lambda done: done.cancelled() or done.exception())
+            self._reading = (url, reading)
+        return await asyncio.shield(self._reading[1])
+
+    def _pooled(self) -> httpx.AsyncClient:
+        """The client this event loop reads the clock with, kept so its connections are reused."""
+        loop = asyncio.get_running_loop()
+        if self._loop is not loop or self._client is None:
+            self._loop, self._client, self._reading = loop, httpx.AsyncClient(timeout=READ_TIMEOUT), None
+        return self._client
+
+
+async def _read(client: httpx.AsyncClient, url: str) -> datetime.datetime | None:
+    """The clock at ``url``'s time, None when it isn't armed (404); a transport error or a 5xx is tried again once."""
+    failure: Exception | None = None
+    for _attempt in range(READ_ATTEMPTS):
+        try:
+            response = await client.get(url)
+        except httpx.TransportError as e:
+            failure = e
+            continue
+        if response.status_code == 404:
+            return None
+        if response.status_code >= 500:
+            failure = httpx.HTTPStatusError(f"{response.status_code}", request=response.request, response=response)
+            continue
+        try:
+            response.raise_for_status()
+            return parse_time(response.json()["virtual_time"])
+        except (httpx.HTTPStatusError, ValueError, KeyError, TypeError) as e:
+            raise ClockUnavailable(f"the universe's clock at {url} answered {response.status_code}: {e}") from e
+    raise ClockUnavailable(f"the universe's clock at {url} can't be read: {type(failure).__name__}: {failure}")
+
+
+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()