agentenv-framework-protocol 0.1.465__tar.gz → 0.1.467__tar.gz

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.465
+Version: 0.1.467
 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
@@ -969,6 +969,31 @@ are the profile's template. The base class adds:
   - `files/choose {paths}`, files in `~/Uploads` for the file chooser open on it, which headless, and so
     alone, it intercepts;
   - `page/state`, the active tab's id, URL and title and the dialog or file chooser open on it.
+  - `cookies/get {urls?}`, `cookies/set {cookies}` and `cookies/delete {name?, domain?, path?}`, on its default
+    context, each cookie as Playwright's `storageState` has it, CDP's `Network.Cookie` fields (`name`, `value`,
+    `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`), so a storage state exported from Playwright loads
+    as is, and a partitioned cookie's `partitionKey` (`{topLevelSite, hasCrossSiteAncestor}`), without which it would
+    be another cookie. `get` returns the cookies a request to any of `urls` would send, as Playwright picks them, else
+    every one; `set` takes a `url`, or a `domain` and a `path` (`/` by default), and may carry `max_age` in place of
+    `expires`: seconds from when it's set, on the computer's clock, which the browser's cookies are judged by. It sets
+    them all at once, so a cookie the browser refuses leaves none set. `delete` removes every cookie with all the
+    fields it's given, every cookie with none, partitioned or not, and says how many. A cookie refused names its
+    fields, never its value;
+  - `local_storage/get {origins?}`, `local_storage/set {origins}` and `local_storage/clear {origins?}`, each origin
+    as `storageState` has it, `{origin, localStorage: [{name, value}]}`. CDP reaches an origin's local storage only
+    through a page of it, so each goes through a hidden page agentenv sends to the origin and serves itself, past any
+    service worker of the origin: the site gets no request and runs no script. The origins answered are as the browser
+    names them (`https://xn--bcher-kva.de` for `https://bücher.de`). With no `origins`, every origin a page or a
+    same-site frame loaded since its server started, and those agentenv set. A cross-site iframe's local storage is
+    partitioned under the site that embeds it, and isn't read, as Playwright's `storageState` doesn't read it either.
+    Agents' CDP connections see each hidden page come and go as a target of type `other`;
+  - `downloads/list` and `downloads/get {guid, write_namespace?}`, a download and, completed, its file: uploaded
+    under the `write_namespace` grant when there is one, else inline, as `data/get` returns files. Inline, the whole
+    file is read into memory and sent base64 in one answer, so a large one belongs under a grant.
+
+  The record's entries are the models in `agentenv_protocol.website_browser` (`OpenTab`, with the tab that opened
+  it as `opener`; `ClosedTab`; `Download`; `Dialog`; `LaunchEntry`; `BrowserRecord`), every field present and null
+  until it's known.
   - `cdp {user}`, `user`'s CDP address once the browser is ready, `http_url` to discover from and
     `ws_url` to connect to, both at the address the call reached it at with a token agentenv mints in
     the path: the same one each time it's asked for. Through the driver they're under

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/README.md

@@ -907,6 +907,31 @@ are the profile's template. The base class adds:
   - `files/choose {paths}`, files in `~/Uploads` for the file chooser open on it, which headless, and so
     alone, it intercepts;
   - `page/state`, the active tab's id, URL and title and the dialog or file chooser open on it.
+  - `cookies/get {urls?}`, `cookies/set {cookies}` and `cookies/delete {name?, domain?, path?}`, on its default
+    context, each cookie as Playwright's `storageState` has it, CDP's `Network.Cookie` fields (`name`, `value`,
+    `domain`, `path`, `expires`, `httpOnly`, `secure`, `sameSite`), so a storage state exported from Playwright loads
+    as is, and a partitioned cookie's `partitionKey` (`{topLevelSite, hasCrossSiteAncestor}`), without which it would
+    be another cookie. `get` returns the cookies a request to any of `urls` would send, as Playwright picks them, else
+    every one; `set` takes a `url`, or a `domain` and a `path` (`/` by default), and may carry `max_age` in place of
+    `expires`: seconds from when it's set, on the computer's clock, which the browser's cookies are judged by. It sets
+    them all at once, so a cookie the browser refuses leaves none set. `delete` removes every cookie with all the
+    fields it's given, every cookie with none, partitioned or not, and says how many. A cookie refused names its
+    fields, never its value;
+  - `local_storage/get {origins?}`, `local_storage/set {origins}` and `local_storage/clear {origins?}`, each origin
+    as `storageState` has it, `{origin, localStorage: [{name, value}]}`. CDP reaches an origin's local storage only
+    through a page of it, so each goes through a hidden page agentenv sends to the origin and serves itself, past any
+    service worker of the origin: the site gets no request and runs no script. The origins answered are as the browser
+    names them (`https://xn--bcher-kva.de` for `https://bücher.de`). With no `origins`, every origin a page or a
+    same-site frame loaded since its server started, and those agentenv set. A cross-site iframe's local storage is
+    partitioned under the site that embeds it, and isn't read, as Playwright's `storageState` doesn't read it either.
+    Agents' CDP connections see each hidden page come and go as a target of type `other`;
+  - `downloads/list` and `downloads/get {guid, write_namespace?}`, a download and, completed, its file: uploaded
+    under the `write_namespace` grant when there is one, else inline, as `data/get` returns files. Inline, the whole
+    file is read into memory and sent base64 in one answer, so a large one belongs under a grant.
+
+  The record's entries are the models in `agentenv_protocol.website_browser` (`OpenTab`, with the tab that opened
+  it as `opener`; `ClosedTab`; `Download`; `Dialog`; `LaunchEntry`; `BrowserRecord`), every field present and null
+  until it's known.
   - `cdp {user}`, `user`'s CDP address once the browser is ready, `http_url` to discover from and
     `ws_url` to connect to, both at the address the call reached it at with a token agentenv mints in
     the path: the same one each time it's asked for. Through the driver they're under

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/pyproject.toml

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

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/src/agentenv_protocol/computer/app_runtime.py

@@ -38,6 +38,7 @@ LAUNCHES = Path(".agentenv/launches")
 EXIT_WAIT_S = 5.0
 #: How long a stopped app may take to exit before it's killed.
 STOP_TIMEOUT_S = 10.0
+HOLD_BOOT_LAUNCH_ENV = "AGENTENV_HOLD_BOOT_LAUNCH"
 
 
 class AppReadiness(BaseModel):
@@ -76,9 +77,10 @@ class AppRuntime:
 
     async def start(self) -> None:
         """Once its X display is up, when it has one, add the app's menu launcher on a desktop and launch a boot app,
-        unless the computer has launched it since it booted, at boot or on demand: a server that restarts leaves the
-        app be, or with ``relaunch_on_start``, for an app only the server that launched it can talk to, stops it and
-        launches it again, whether it was launched at boot or on demand."""
+        unless the computer has launched it since it booted, at boot or on demand, or its boot launch is held
+        (``boot_launch_held``): a server that restarts leaves the app be, or with ``relaunch_on_start``, for an app
+        only the server that launched it can talk to, stops it and launches it again, whether it was launched at boot
+        or on demand."""
         if self.launch is None:
             return
         if os.environ.get("DISPLAY"):
@@ -87,7 +89,7 @@ class AppRuntime:
             session.add_launcher(os.environ["ENVIRONMENT_NAME"], Path.cwd())
         launched = _launched_at() is not None
         relaunch = self.relaunch_on_start and launched
-        if relaunch or (self.launch.at == "boot" and not launched):
+        if relaunch or (self.launch.at == "boot" and not launched and not boot_launch_held()):
             try:
                 if relaunch:
                     await self.stop_app()
@@ -192,6 +194,14 @@ class AppRuntime:
         return None if passed else f"@ready_check {name} returned {passed!r}"
 
 
+def boot_launch_held() -> bool:
+    """Whether the computer holds its boot apps' launches (``HOLD_BOOT_LAUNCH_ENV`` is ``1`` in its environment): each
+    app's server then leaves its boot app unlaunched, the driver counts it ready until something launches it, and
+    whoever booted the computer launches each one through ``computer-app/v1``'s ``launch`` once it has set the computer
+    up for them, as a deploy routing the run's websites does once their names, CA and proxy are in place."""
+    return os.environ.get(HOLD_BOOT_LAUNCH_ENV) == "1"
+
+
 def _mark() -> Path:
     return LAUNCHED / Path.cwd().name
 

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/src/agentenv_protocol/computer/apps.py

@@ -1,9 +1,10 @@
 """The apps composed onto a computer, as its driver finds them, whether each is ready, and how the driver fronts them.
 Each app's own server answers on its folder's socket (``serve_app``): its card says how the app launches and which
 paths it owns, and its ``computer-app/v1`` ``ready`` whether it's ready. Every app's server must answer before the
-computer is ready; an app that starts with the computer must also be ready, and a ``demand`` app is checked once
-something launches it. The driver lists each app as a child environment named for its folder, its card's paths under
-``/svc/<name>/``, where it forwards each request to the app's server (``svc``)."""
+computer is ready; an app that starts with the computer must also be ready, and a ``demand`` app, or a boot app
+while the computer holds its launch (``boot_launch_held``), is checked once something launches it. The driver lists
+each app as a child environment named for its folder, its card's paths under ``/svc/<name>/``, where it forwards each
+request to the app's server (``svc``)."""
 from __future__ import annotations
 
 import asyncio
@@ -17,7 +18,7 @@ import httpx
 from .. import client
 from ..types import RPC_PATH, WELL_KNOWN_PATH, EnvironmentCard
 from .app import COMPUTER_APP, FAILURE, SOCKET
-from .app_runtime import CHECK_TIMEOUT_S, LAUNCHES, AppReadiness
+from .app_runtime import CHECK_TIMEOUT_S, LAUNCHES, AppReadiness, boot_launch_held
 from .operations import ReadyCheck
 
 #: Where a composed computer installs its apps, a folder each.
@@ -45,6 +46,8 @@ async def check(folder: Path) -> ReadyCheck:
         return ReadyCheck(f"app {name}", False, _unanswered(folder))
     if launch is not None and launch["at"] == "demand" and not answer.launched:
         return ReadyCheck(f"app {name}", True, "its server answers; it launches on demand")
+    if launch is not None and boot_launch_held() and not answer.launched:
+        return ReadyCheck(f"app {name}", True, "its server answers; its boot launch is held")
     if answer.ready:
         return ReadyCheck(f"app {name}", True, "ready")
     when = (f"not ready after {answer.timeout_s:.0f} s" if answer.waited_s > answer.timeout_s

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/src/agentenv_protocol/website/__init__.py

@@ -21,6 +21,7 @@ from .readiness import (
     DEFAULT_HEALTH_PATH,
     READY_TIMEOUT_S,
     SITE_READY_TIMEOUT_S,
+    WEBSITE_BROWSE_URL_PARAM,
     WEBSITE_EXTENSION_URI,
     WEBSITE_READY_OP,
     WebsiteReadiness,
@@ -36,6 +37,6 @@ __all__ = [
     "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_READY_OP", "WEBSITE_BROWSE_URL_PARAM", "READY_TIMEOUT_S", "SITE_READY_TIMEOUT_S", "WebsiteReadiness",
     "website_readiness", "env_readiness",
 ]

{agentenv_framework_protocol-0.1.465 → agentenv_framework_protocol-0.1.467}/src/agentenv_protocol/website/readiness.py

@@ -4,7 +4,9 @@ it is usable now through its card's ``urn:agentenv:website/v1`` ``ready`` (``WEB
 of an env, a composed card's children or a single site's own card, and answers for the env as a whole; asking one
 site may take ``READY_TIMEOUT_S`` by default. A site may say how long it may take to be ready (``timeout_s``,
 ``SITE_READY_TIMEOUT_S`` when it says nothing). A server whose card has no ``ready`` is asked at its health path,
-``DEFAULT_HEALTH_PATH`` unless it names one, which is deprecated."""
+``DEFAULT_HEALTH_PATH`` unless it names one, which is deprecated. A composer serving a site to a browser at a route of
+its own, as the env gateway serves ``/website/<name>/``, says where on the site's ``website/v1`` params, as
+``WEBSITE_BROWSE_URL_PARAM``: a path joined onto the composed card's address, or a full URL."""
 from __future__ import annotations
 
 import asyncio
@@ -17,6 +19,7 @@ from ..client import find_extension_method, invoke_extension
 
 WEBSITE_EXTENSION_URI = "urn:agentenv:website/v1"
 WEBSITE_READY_OP = "ready"
+WEBSITE_BROWSE_URL_PARAM = "browse_url"
 READY_TIMEOUT_S = 10.0
 SITE_READY_TIMEOUT_S = 300.0
 DEFAULT_HEALTH_PATH = "/api/health"

agentenv_framework_protocol-0.1.467/src/agentenv_protocol/website_browser/__init__.py

@@ -0,0 +1,23 @@
+"""WebsiteBrowserEnvironment: a website browser as a computer app, run inside a computer or alone. A subclass says how
+its build installs and starts; this class adds what agentenv owns, the same in both: its flags after the subclass's
+command, the unattended-use policies, a CDP connection over the browser's debugging pipe, the settings every browser
+takes, a fresh cache and the deploy's prompt answers at every launch, another window for a launch while it runs, its
+skill and ``browser/v1`` on its card. It runs alone, headless, on a computer with no display, a browser computer's,
+whose screen is its page; which site proxy it goes through comes from a variable agentenv sets, never from its
+settings."""
+from .control import (ACTIVE_CHECK_TIMEOUT_S, AGENT, AGENTENV, CAPTURE_TIMEOUT_S, DOWNLOADS, EXIT, HASH_CHUNK_BYTES,
+                      PAGE_INPUT, PAGES, PIN_TIMEOUT_S, STOP, UNKNOWN, UNNAVIGATED_CAPTURE_TIMEOUT_S, UPLOADS,
+                      BrowserControl)
+from .devtools import MAX_MESSAGE_BYTES, PIPE_IN, PIPE_OUT, DevToolsError, DevToolsPipe
+from .environment import (ALONE_BYPASS, BLOCK, BROWSER, COMPUTER_BYPASS, OWNED_FLAGS, POLICIES, READY_POLL_S,
+                          SHM_MIN_BYTES, SITE_PROXY_ENV, SKILL, BrowserSettings, WebsiteBrowserEnvironment, Window)
+from .shapes import (BrowserRecord, ClosedTab, Cookie, CookieToSet, Dialog, Download, LaunchEntry, OpenTab,
+                     OriginStorage, PartitionKey, StorageItem, origin_of)
+
+__all__ = ["ACTIVE_CHECK_TIMEOUT_S", "AGENT", "AGENTENV", "ALONE_BYPASS", "BLOCK", "BROWSER", "CAPTURE_TIMEOUT_S",
+           "COMPUTER_BYPASS", "DOWNLOADS", "EXIT", "HASH_CHUNK_BYTES", "MAX_MESSAGE_BYTES", "OWNED_FLAGS", "PAGE_INPUT",
+           "PAGES", "PIN_TIMEOUT_S", "PIPE_IN", "PIPE_OUT", "POLICIES", "READY_POLL_S", "SHM_MIN_BYTES",
+           "SITE_PROXY_ENV", "SKILL", "STOP", "UNKNOWN", "UNNAVIGATED_CAPTURE_TIMEOUT_S", "UPLOADS", "BrowserControl",
+           "BrowserSettings", "DevToolsError", "DevToolsPipe", "WebsiteBrowserEnvironment", "Window",
+           "BrowserRecord", "ClosedTab", "Cookie", "CookieToSet", "Dialog", "Download", "LaunchEntry", "OpenTab",
+           "OriginStorage", "PartitionKey", "StorageItem", "origin_of"]