agentenv-framework-protocol 0.1.471__tar.gz → 0.1.473__tar.gz

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.471
+Version: 0.1.473
 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
@@ -894,13 +894,19 @@ in the session (`agentenv_protocol.computer.session`) is Linux's.
 
 The server serves the app's data plane and its skill. With `paths` alone, `data/add` writes the files
 it's given under them and refuses any other path, or one a link leads out of them; `data/get`
-returns the files there, a file tree; and `data/reset` puts them back as the server found them when
+returns the files there, a file tree, copied with every process of the app paused (SIGSTOP) so they
+are of one moment, and sent from the copy once it runs again; and `data/reset` puts them back as the server found them when
 it first started on this boot, which is the app as installed. Hooks serve what they mark instead.
 A hook's `data/add` parts come as they were sent, inline or as a read grant, and
 `part_bytes(part)` returns a part's bytes either way. Either way the base class takes data calls and
 launches one at a time, runs a load and a reset with the app stopped and relaunches it after,
 follows a failed load with a reset, and fails a call that runs past `data_timeout_s` (300 s); a sync
-hook runs in a thread, which the reset and relaunch after it wait for. The driver fronts its apps:
+hook runs in a thread, which the reset and relaunch after it wait for. An app whose hooks serve an
+operation on the running app names it in `data_live` (a website browser's load sets cookies over its
+pipe), and the base class doesn't stop it for that one; a reset after such a load that failed still
+stops and relaunches it. `_resets_failed_add()` says whether a failed load is followed by a reset at
+all, always by default; and `data_keeps_paths` has the server keep the app's paths as installed for a
+reset hook of its own, which `app_data.reset(paths)` puts back, as the default reset does. The driver fronts its apps:
 its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
 requests to the app's server, taking the control token:
 
@@ -918,6 +924,11 @@ agents reach this way without the control token: the driver reads them from the
 (`computer-app/v1`'s `agent_routes`) and lets a call under one through, while the app checks it
 itself. A path with a `.` or `..` segment, escaped or not, never counts as under one.
 
+Once an agent acts in the computer, by any tool call on the driver's `/mcp` or a call on a route an
+app opens to agents, the driver writes `.agentenv/agent-acted` in each app's folder, and
+`agent_acted()` reads it from the app's own: a fresh computer starts without it, and an app that resets
+removes its own with `forget_agent_acted()`. agentenv's own calls, with the control token, don't count.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores (`browser: true` for a website browser), and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as
 JSON, or a driver's `DriverDeclaration`, without the class's own dependencies installed.
@@ -989,8 +1000,9 @@ are the profile's template. The base class adds:
   `Input.dispatchKeyEvent`, `Input.insertText`), sent to it in order. Also framework-only, for page
   drivers and agentenv's own steps alike:
   - `navigate {url}` and `history {direction}` (`back`, `forward` or `reload`), in the active tab;
-  - `tabs/list`, `tabs/open {url?}`, `tabs/activate {tab}` and `tabs/close {tab}`, by the browser's own tab
-    ids. The active tab is the one a dialog is open on, else the visible one whose page has focus (a hidden
+  - `tabs/list`, `tabs/open {url?, background?}`, `tabs/activate {tab}` and `tabs/close {tab}`, by the browser's
+    own tab ids. A tab opened with `background` opens behind the active tab, which stays active; otherwise it comes
+    to the front. The active tab is the one a dialog is open on, else the visible one whose page has focus (a hidden
     tab's page that had input still says it has focus), else the one agentenv last brought to the front.
     Headless, a tab opened at a URL opens blank and goes there once it's held to the window's size;
   - `dialog/answer {accept, text?}`, the agent's answer to the dialog open on the active tab;
@@ -1019,6 +1031,26 @@ are the profile's template. The base class adds:
     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 browser's data plane is a file tree, every file by its path under the session user's home:
+  - `data/get` returns its state as `browser-state.json` (`BrowserState`: `cookies` and `local_storage`
+    as above, `tabs`, `closed_tabs`, `downloads` and `clock`, `real` with its `now`); its profile's files,
+    each database with its journal or log, copied in one pass with the browser paused once its state is
+    read, so the files are of one moment, without caches (`Cache`, `Code Cache`,
+    `GPUCache`, the shader and Dawn caches, `CacheStorage`, `ScriptCache`, `Crashpad`) or locks
+    (`Singleton*`); and its finished downloads.
+  - `data/add` applies such a state while the browser runs, from `browser-state.json` or a data part of
+    its shape (`StateToLoad`: `cookies`, `local_storage` and `tabs`; what it records of the past is left),
+    after files written by their path: profile files restore the profile to exactly them, with the
+    browser stopped and relaunched first, and files under `~/Downloads` and `~/Uploads` land there; any
+    other path is refused before anything is applied. A load's `tabs` open in place of the open ones,
+    the active one in front; with none, a load that changes cookies or local storage sends the start tabs
+    back to their `start_urls`, so a page loaded before it shows it. Once an agent has acted, a load
+    can't change the profile or the tabs, the start tabs stay as they are, and a load that fails isn't
+    reset: its error says what it had applied.
+  - `data/reset` ends every CDP address, puts the profile back as installed, empties `~/Downloads` and
+    `~/Uploads`, starts its record over and forgets that an agent acted; its data plane relaunches it at
+    its start tabs.
+
   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.

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/README.md

@@ -829,13 +829,19 @@ in the session (`agentenv_protocol.computer.session`) is Linux's.
 
 The server serves the app's data plane and its skill. With `paths` alone, `data/add` writes the files
 it's given under them and refuses any other path, or one a link leads out of them; `data/get`
-returns the files there, a file tree; and `data/reset` puts them back as the server found them when
+returns the files there, a file tree, copied with every process of the app paused (SIGSTOP) so they
+are of one moment, and sent from the copy once it runs again; and `data/reset` puts them back as the server found them when
 it first started on this boot, which is the app as installed. Hooks serve what they mark instead.
 A hook's `data/add` parts come as they were sent, inline or as a read grant, and
 `part_bytes(part)` returns a part's bytes either way. Either way the base class takes data calls and
 launches one at a time, runs a load and a reset with the app stopped and relaunches it after,
 follows a failed load with a reset, and fails a call that runs past `data_timeout_s` (300 s); a sync
-hook runs in a thread, which the reset and relaunch after it wait for. The driver fronts its apps:
+hook runs in a thread, which the reset and relaunch after it wait for. An app whose hooks serve an
+operation on the running app names it in `data_live` (a website browser's load sets cookies over its
+pipe), and the base class doesn't stop it for that one; a reset after such a load that failed still
+stops and relaunches it. `_resets_failed_add()` says whether a failed load is followed by a reset at
+all, always by default; and `data_keeps_paths` has the server keep the app's paths as installed for a
+reset hook of its own, which `app_data.reset(paths)` puts back, as the default reset does. The driver fronts its apps:
 its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
 requests to the app's server, taking the control token:
 
@@ -853,6 +859,11 @@ agents reach this way without the control token: the driver reads them from the
 (`computer-app/v1`'s `agent_routes`) and lets a call under one through, while the app checks it
 itself. A path with a `.` or `..` segment, escaped or not, never counts as under one.
 
+Once an agent acts in the computer, by any tool call on the driver's `/mcp` or a call on a route an
+app opens to agents, the driver writes `.agentenv/agent-acted` in each app's folder, and
+`agent_acted()` reads it from the app's own: a fresh computer starts without it, and an app that resets
+removes its own with `forget_agent_acted()`. agentenv's own calls, with the control token, don't count.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores (`browser: true` for a website browser), and `python -m agentenv_protocol.computer._declare <folder> <file> <class>` prints it as
 JSON, or a driver's `DriverDeclaration`, without the class's own dependencies installed.
@@ -924,8 +935,9 @@ are the profile's template. The base class adds:
   `Input.dispatchKeyEvent`, `Input.insertText`), sent to it in order. Also framework-only, for page
   drivers and agentenv's own steps alike:
   - `navigate {url}` and `history {direction}` (`back`, `forward` or `reload`), in the active tab;
-  - `tabs/list`, `tabs/open {url?}`, `tabs/activate {tab}` and `tabs/close {tab}`, by the browser's own tab
-    ids. The active tab is the one a dialog is open on, else the visible one whose page has focus (a hidden
+  - `tabs/list`, `tabs/open {url?, background?}`, `tabs/activate {tab}` and `tabs/close {tab}`, by the browser's
+    own tab ids. A tab opened with `background` opens behind the active tab, which stays active; otherwise it comes
+    to the front. The active tab is the one a dialog is open on, else the visible one whose page has focus (a hidden
     tab's page that had input still says it has focus), else the one agentenv last brought to the front.
     Headless, a tab opened at a URL opens blank and goes there once it's held to the window's size;
   - `dialog/answer {accept, text?}`, the agent's answer to the dialog open on the active tab;
@@ -954,6 +966,26 @@ are the profile's template. The base class adds:
     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 browser's data plane is a file tree, every file by its path under the session user's home:
+  - `data/get` returns its state as `browser-state.json` (`BrowserState`: `cookies` and `local_storage`
+    as above, `tabs`, `closed_tabs`, `downloads` and `clock`, `real` with its `now`); its profile's files,
+    each database with its journal or log, copied in one pass with the browser paused once its state is
+    read, so the files are of one moment, without caches (`Cache`, `Code Cache`,
+    `GPUCache`, the shader and Dawn caches, `CacheStorage`, `ScriptCache`, `Crashpad`) or locks
+    (`Singleton*`); and its finished downloads.
+  - `data/add` applies such a state while the browser runs, from `browser-state.json` or a data part of
+    its shape (`StateToLoad`: `cookies`, `local_storage` and `tabs`; what it records of the past is left),
+    after files written by their path: profile files restore the profile to exactly them, with the
+    browser stopped and relaunched first, and files under `~/Downloads` and `~/Uploads` land there; any
+    other path is refused before anything is applied. A load's `tabs` open in place of the open ones,
+    the active one in front; with none, a load that changes cookies or local storage sends the start tabs
+    back to their `start_urls`, so a page loaded before it shows it. Once an agent has acted, a load
+    can't change the profile or the tabs, the start tabs stay as they are, and a load that fails isn't
+    reset: its error says what it had applied.
+  - `data/reset` ends every CDP address, puts the profile back as installed, empties `~/Downloads` and
+    `~/Uploads`, starts its record over and forgets that an agent acted; its data plane relaunches it at
+    its start tabs.
+
   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.

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/pyproject.toml

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

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/browser_cdp.py

@@ -111,6 +111,11 @@ class Tokens:
             self._save()
         return self._minted[user]
 
+    def revoke_all(self) -> None:
+        """Every address minted so far ended, as a reset ends them."""
+        self._minted, self._known = {}, {}
+        self._save()
+
     def address(self, token: str) -> Optional[Address]:
         """The address ``token`` was minted for, or None for one that wasn't."""
         known = self._known.get(_hash(token))

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/app.py

@@ -43,6 +43,9 @@ WINDOW_KEYS = frozenset({"class", "instance", "title"})
 COMPUTER_APP = "urn:agentenv:computer-app/v1"
 #: Where an app's own server listens, in the app's folder, and where it says why it last failed to start.
 SOCKET = Path(".agentenv/server.sock")
+#: Written in an app's folder by its computer's driver once an agent acts there, by a tool call or on a route the app
+#: opens to agents: a fresh computer starts without it, and an app that resets removes its own.
+AGENT_ACTED = Path(".agentenv/agent-acted")
 FAILURE = Path(".agentenv/server.failure")
 #: The values of an app's build settings its env fixes in its computer's image, in the app's folder.
 BUILD_SETTINGS = Path(".agentenv/build_settings.json")
@@ -359,6 +362,17 @@ def _named(os_types: Union[str, list[str], None]) -> Optional[list[str]]:
     return None if os_types is None else [os_types] if isinstance(os_types, str) else list(os_types)
 
 
+def agent_acted() -> bool:
+    """Whether an agent has acted in this app's computer since the computer started or the app last reset, as its
+    driver notes; read from the app's own folder."""
+    return AGENT_ACTED.exists()
+
+
+def forget_agent_acted() -> None:
+    """Start over, as an app that has reset: no agent has acted since."""
+    AGENT_ACTED.unlink(missing_ok=True)
+
+
 class ComputerAppEnvironment(AgentEnvEnvironment):
     """Subclass it, declare it with ``@computer_app`` and an OS decorator for each OS (``@linux``), and set ``skill`` as
     a class attribute; a deploy's settings arrive as ``self.settings``, those its env fixes at build as
@@ -383,6 +397,11 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
     skill: ClassVar[Optional[str]] = None
     #: How long one of its data calls may take, a hook or its paths' default, before it fails.
     data_timeout_s: ClassVar[float] = 300.0
+    #: The data operations its hooks serve on the running app, which its data plane neither stops it for nor
+    #: relaunches it after; and whether its server keeps its paths as installed for a reset hook of its own to put
+    #: back (``app_data.reset``), as it does for the default reset.
+    data_live: ClassVar[frozenset[str]] = frozenset()
+    data_keeps_paths: ClassVar[bool] = False
     #: Path prefixes of its own server's routes, each ending in ``/``, that agents reach through the driver without the
     #: computer's control token; the app checks a call to one itself.
     agent_routes: ClassVar[tuple[str, ...]] = ()
@@ -426,7 +445,8 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
             launch_running=self._launch_running())
         self._computer_app_data = AppDataPlane(
             self._computer_app, {op: getattr(self, name) for op, name in cls._data_hooks.items()}, self.paths,
-            cls.data_timeout_s)
+            cls.data_timeout_s, live=cls.data_live, keeps_paths=cls.data_keeps_paths,
+            resets_failed_add=self._resets_failed_add)
 
     def _launch_for(self, launch: Launch) -> Launch:
         """The launch its server uses, from the one declared for its OS, whose ``ready`` timeout it keeps: as
@@ -449,6 +469,10 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         """What a launch does while it runs instead of starting a second copy: nothing, so another copy starts."""
         return None
 
+    def _resets_failed_add(self) -> bool:
+        """Whether a load that fails is followed by a reset, so the app isn't left half loaded: always."""
+        return True
+
     @classmethod
     def settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
         """Its ``Settings`` on ``os_type``, with the fields its OS adds."""

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/app_data.py

@@ -5,10 +5,12 @@ boot, which is the app as installed, since every boot starts from the computer's
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import functools
 import inspect
 import logging
 import shutil
+import tempfile
 from collections.abc import Callable
 from pathlib import Path, PurePosixPath
 from typing import TYPE_CHECKING, Any, Optional
@@ -16,7 +18,7 @@ from typing import TYPE_CHECKING, Any, Optional
 from ..agent_env_environment import OP_ADD_DATA, OP_GET_DATA, OP_RESET_DATA
 from ..transfers import WriteNamespaceGrant
 from ..types import METHOD_ADD, METHOD_RESET, FilePart, uploaded_object_path
-from .dataplane import file_parts, part_bytes
+from .dataplane import data_files, file_parts, part_bytes
 
 if TYPE_CHECKING:
     from .app_runtime import AppRuntime
@@ -31,21 +33,28 @@ INITIAL = Path(".agentenv/initial")
 
 class AppDataPlane:
     """An app's data plane, served around its contract: one data call or launch at a time; a load and a reset stop the
-    running app first and relaunch it after, and a load that fails is followed by a reset. A call fails once it runs
+    running app first and relaunch it after, but for those the app serves live, and a load that fails is followed by a
+    reset, when the app says so. A call fails once it runs
     past ``timeout_s`` and is cancelled: what awaits stops at once, but a thread can't be stopped, so a sync hook's or
     a default's thread is waited for, as are the reset and relaunch after it and the next call."""
 
-    def __init__(self, runtime: AppRuntime, hooks: dict[str, Callable], paths: list[str], timeout_s: float) -> None:
+    def __init__(self, runtime: AppRuntime, hooks: dict[str, Callable], paths: list[str], timeout_s: float, *,
+                 live: frozenset[str] = frozenset(), keeps_paths: bool = False,
+                 resets_failed_add: Callable[[], bool] = lambda: True) -> None:
         self.runtime = runtime
         self.hooks = hooks
         self.paths = paths
         self.timeout_s = timeout_s
+        #: The operations served on the running app; whether a hook's reset needs the paths as installed; and whether
+        #: a load that fails is followed by a reset now.
+        self.live, self.keeps_paths, self.resets_failed_add = live, keeps_paths, resets_failed_add
         self.turn = asyncio.Lock()
         self.changing: set[asyncio.Task] = set()
 
     def keep_initial(self) -> None:
-        """Keep the app's paths as installed, before anything changes them, when they serve its data."""
-        if self.paths and not self.hooks:
+        """Keep the app's paths as installed, before anything changes them, when they serve its data or its own reset
+        puts them back."""
+        if self.paths and (not self.hooks or self.keeps_paths):
             keep_initial(self.paths)
 
     async def call(self, op: str, *args: Any) -> Any:
@@ -71,14 +80,20 @@ class AppDataPlane:
 
     async def _change(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> None:
         """``op`` between the app's stop and its relaunch, answered on ``answer``: as it ends, or once it runs past
-        ``timeout_s``."""
+        ``timeout_s``. A live one runs on the running app, which a reset after it fails stops and relaunches; an app
+        it ran on is running again after it fails, though the op stopped it."""
         try:
-            running = op != OP_GET_DATA and await self.runtime.stop_app()
+            running = op != OP_GET_DATA and op not in self.live and await self.runtime.stop_app()
+            ran = op in self.live and self.runtime.running()
             try:
                 result = await self._within(op, served, args, answer)
             except Exception:
-                if op == OP_ADD_DATA:
+                if op == OP_ADD_DATA and self.resets_failed_add():
+                    if op in self.live:
+                        running = await self.runtime.stop_app() or ran
                     await self._undo(answer)
+                elif op in self.live:
+                    running = ran and not self.runtime.running()
                 raise
             finally:
                 if running:
@@ -116,7 +131,7 @@ class AppDataPlane:
         if not self.paths:
             return None
         return {OP_ADD_DATA: functools.partial(add, paths=self.paths),
-                OP_GET_DATA: functools.partial(get, self.paths),
+                OP_GET_DATA: functools.partial(get, self.paths, self.runtime.paused),
                 OP_RESET_DATA: functools.partial(reset, self.paths)}[op]
 
     async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
@@ -159,12 +174,18 @@ async def add(parts: list, paths: list[str]) -> None:
         if not any(PurePosixPath(path).is_relative_to(owned) for owned in paths):
             raise ValueError(f"{path!r} is under none of this app's paths: {', '.join(paths)}")
         files[path] = await part_bytes(part)
-    await in_thread(_write, Path.home(), files, paths)
+    await in_thread(write_within, Path.home(), files, paths)
 
 
-async def get(paths: list[str], write_namespace: Optional[WriteNamespaceGrant]) -> list:
-    """A part for each file under ``paths``."""
-    return await file_parts(Path.home(), paths, write_namespace)
+async def get(paths: list[str], paused: Callable[[], contextlib.AbstractContextManager],
+              write_namespace: Optional[WriteNamespaceGrant]) -> list:
+    """A part for each file under ``paths``, copied with the app ``paused``, so they are of one moment, and sent from
+    the copy once it runs again."""
+    INITIAL.parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(dir=INITIAL.parent) as staging:
+        with paused():
+            await in_thread(_stage, Path.home(), paths, Path(staging))
+        return await file_parts(Path(staging), paths, write_namespace)
 
 
 async def reset(paths: list[str]) -> None:
@@ -191,7 +212,8 @@ async def in_thread(fn: Callable, *args: Any) -> Any:
         raise
 
 
-def _write(home: Path, files: dict[str, bytes], paths: list[str]) -> None:
+def write_within(home: Path, files: dict[str, bytes], paths: list[str]) -> None:
+    """Each file at its path under the home, none written when one leads out of ``paths`` through a link."""
     owned = [(home / path).resolve() for path in paths]
     if linked := [path for path in files if not any((home / path).resolve().is_relative_to(o) for o in owned)]:
         raise ValueError(f"{', '.join(map(repr, linked))} lead out of this app's paths through a link")
@@ -211,6 +233,16 @@ def _restore(home: Path, paths: list[str]) -> None:
         _copy(INITIAL / path, target)
 
 
+def _stage(home: Path, paths: list[str], staging: Path) -> None:
+    """A copy in ``staging`` of each file an export of ``paths`` sends, by its path: a link's target, inside the home, as
+    a file, and no socket or pipe."""
+    for relative, source in data_files(home, paths):
+        target = staging / relative
+        target.parent.mkdir(parents=True, exist_ok=True)
+        with contextlib.suppress(FileNotFoundError):
+            shutil.copy2(source, target)
+
+
 def _copy(source: Path, target: Path) -> None:
     if source.is_dir() and not source.is_symlink():
         shutil.copytree(source, target, symlinks=True)

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/app_runtime.py

@@ -4,6 +4,7 @@ of the boot, stops the app it launched, and says whether the app is ready, its c
 from __future__ import annotations
 
 import asyncio
+import contextlib
 import inspect
 import json
 import os
@@ -133,6 +134,16 @@ class AppRuntime:
         await session.stop(pid, STOP_TIMEOUT_S)
         return True
 
+    def running(self) -> bool:
+        """Whether the app this server launched last runs."""
+        return _running() is not None
+
+    def paused(self) -> contextlib.AbstractContextManager:
+        """The app this server launched last, every process of it, paused while the block runs, so a copy of its files
+        taken meanwhile is of one moment."""
+        pid = _running()
+        return session.paused(pid) if pid is not None else contextlib.nullcontext()
+
     def exited(self) -> bool:
         """Log that the app this server launched last ended on its own, with its exit code or the signal that ended
         it, unless the server stopped it; whether it did."""

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/apps.py

@@ -10,6 +10,7 @@ from __future__ import annotations
 import asyncio
 import copy
 import json
+from datetime import datetime, timezone
 from pathlib import Path
 from typing import Optional
 
@@ -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 import AGENT_ACTED, COMPUTER_APP, FAILURE, SOCKET
 from .app_runtime import CHECK_TIMEOUT_S, LAUNCHES, AppReadiness, boot_launch_held
 from .operations import ReadyCheck
 
@@ -151,3 +152,15 @@ def _unanswered(folder: Path) -> str:
 def _client(socket: Path) -> httpx.AsyncClient:
     return httpx.AsyncClient(transport=httpx.AsyncHTTPTransport(uds=str(socket)), base_url="http://app",
                              timeout=ANSWER_TIMEOUT_S)
+
+
+def note_agent_acted(folders: list[Path]) -> None:
+    """Note in each app's folder that an agent has acted in the computer, where it isn't noted yet."""
+    for folder in folders:
+        marker = folder / AGENT_ACTED
+        if not marker.exists() and marker.parent.is_dir():
+            marker.write_text(_now())
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat()

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/dataplane.py

@@ -66,7 +66,7 @@ async def file_parts(home: Path, paths: list[str], write_namespace: Optional[Wri
     """A part for each file under ``paths`` of ``home`` but under none of ``leaving_out``, naming its path relative to
     ``home``: uploaded under ``write_namespace`` when there is one, else inline. A file a running app removes before it's
     read is left out."""
-    files = [(relative, source) for relative, source in _data_files(home, paths)
+    files = [(relative, source) for relative, source in data_files(home, paths)
              if not any(PurePosixPath(relative).is_relative_to(owned) for owned in leaving_out)]
     parts = []
     if write_namespace is not None:
@@ -125,7 +125,7 @@ async def _get_url(file: FileWithUri) -> bytes:
     return bytes(data)
 
 
-def _data_files(home: Path, paths: list[str]) -> list[tuple[str, Path]]:
+def data_files(home: Path, paths: list[str]) -> list[tuple[str, Path]]:
     """Every file under ``paths``, by its path relative to the home; a path not there yet is skipped."""
     root = home.resolve()
     found: dict[str, Path] = {}

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/driver.py

@@ -118,6 +118,12 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         card = EnvironmentCard(**{**config, "name": config.get("name") or cls.__name__})
         return AgentEnvFastMCPApplication(card, driver).environment_card
 
+    def on_tool_call(self, context: ToolContext) -> Any:
+        """Note that an agent has acted, for the apps whose loads change what's on screen only before one has: a
+        subclass that has its own calls this one too."""
+        apps.note_agent_acted(self._computer.apps)
+        return None
+
     def has(self, capability: str) -> bool:
         """Whether an operation, or a whole group (``pointer``, ``keyboard``), works on this platform."""
         return self._computer.has(capability)
@@ -177,7 +183,10 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         if not await self._computer_allows(folder, request):
             return _error_response(AgentEnvError(
                 "unauthorized", "this route is agent-env's own: it takes the env's control token", status=401))
-        return await svc.forward(folder, name, request)
+        answer = await svc.forward(folder, name, request)
+        if answer.status_code < 400 and not control_check()(request.headers):
+            apps.note_agent_acted(self._computer.apps)
+        return answer
 
     async def _computer_relay(self, websocket: WebSocket) -> None:
         """A WebSocket under ``/svc/<name>/``, relayed both ways to the app named so; refused, before it opens, with no
@@ -186,7 +195,8 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
         if (folder := self._computer_app_folder(name)) is None or not await self._computer_allows(folder, websocket):
             await websocket.close(code=1008)
             return
-        await svc.relay(folder, name, websocket)
+        agent = not control_check()(websocket.headers)
+        await svc.relay(folder, name, websocket, (lambda: apps.note_agent_acted(self._computer.apps)) if agent else None)
 
     # The card: what the driver's operations support.
 

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/session.py

@@ -9,7 +9,7 @@ import re
 import signal
 import sys
 from pathlib import Path
-from typing import Optional
+from typing import Iterator, Optional
 
 #: How often a starting session is looked for.
 POLL_S = 0.2
@@ -68,13 +68,15 @@ async def returncode(pid: int, timeout_s: float) -> Optional[int]:
 
 
 async def stop(pid: int, timeout_s: float) -> None:
-    """End the session ``launch`` started as ``pid``, every process in it: asked to exit, then killed after
-    ``timeout_s``. No one asks how it exited once it's stopped."""
+    """End the session ``launch`` started as ``pid``, every process in it: asked to exit, a paused one continued so it
+    can, then killed after ``timeout_s``. No one asks how it exited once it's stopped."""
     _exits.pop(pid, None)
     try:
         os.killpg(pid, signal.SIGTERM)
     except ProcessLookupError:
         return
+    with contextlib.suppress(ProcessLookupError, PermissionError):  # macOS refuses a group of zombies alone
+        os.killpg(pid, signal.SIGCONT)
     try:
         await asyncio.wait_for(_exited(pid), timeout_s)
     except TimeoutError:
@@ -82,6 +84,21 @@ async def stop(pid: int, timeout_s: float) -> None:
             os.killpg(pid, signal.SIGKILL)
 
 
+@contextlib.contextmanager
+def paused(pid: int) -> Iterator[None]:
+    """Every process of the session ``launch`` started as ``pid`` stopped while the block runs, and continued after."""
+    try:
+        os.killpg(pid, signal.SIGSTOP)
+    except (ProcessLookupError, PermissionError):
+        yield
+        return
+    try:
+        yield
+    finally:
+        with contextlib.suppress(ProcessLookupError, PermissionError):
+            os.killpg(pid, signal.SIGCONT)
+
+
 def alive(pid: int) -> bool:
     """Whether a process of the session ``launch`` started as ``pid`` is running, its first or one it started."""
     try:

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/computer/svc.py

@@ -7,8 +7,9 @@ import asyncio
 import contextlib
 import logging
 import re
-from collections.abc import AsyncIterator, Iterable
+from collections.abc import AsyncIterator, Callable, Iterable
 from pathlib import Path
+from typing import Optional
 from urllib.parse import quote, unquote
 
 import httpx
@@ -148,9 +149,10 @@ async def forward(folder: Path, name: str, request: Request) -> Response:
     return response
 
 
-async def relay(folder: Path, name: str, websocket: WebSocket) -> None:
-    """``websocket`` relayed both ways to the app ``name``'s server in ``folder`` until either side closes; refused,
-    before it opens, with a Host that isn't a host and port, or with the app's server not answering."""
+async def relay(folder: Path, name: str, websocket: WebSocket, opened: Optional[Callable[[], None]] = None) -> None:
+    """``websocket`` relayed both ways to the app ``name``'s server in ``folder`` until either side closes, ``opened``
+    called once the app has taken it; refused, before it opens, with a Host that isn't a host and port, or with the app's
+    server not answering."""
     host = websocket.headers.get("host", "")
     if host and not HOST.fullmatch(host):
         await websocket.close(code=1008)
@@ -168,6 +170,8 @@ async def relay(folder: Path, name: str, websocket: WebSocket) -> None:
         return
     async with upstream:
         await websocket.accept(subprotocol=upstream.subprotocol)
+        if opened is not None:
+            opened()
         await _both_ways(websocket, upstream)
 
 

{agentenv_framework_protocol-0.1.471 → agentenv_framework_protocol-0.1.473}/src/agentenv_protocol/website_browser/control.py

@@ -120,19 +120,63 @@ class BrowserControl:
         active = await self.active_tab()
         return [OpenTab(**tab, active=tab["id"] == active).model_dump() for tab in self.tabs.values()]
 
-    async def open_tab(self, url: Optional[str] = None) -> str:
-        """A new tab at ``url``, else blank, brought to the front; its id. Headless, it opens blank and goes to ``url``
-        once it's held to the window's size, so its page loads at that size."""
+    async def open_tab(self, url: Optional[str] = None, background: bool = False) -> str:
+        """A new tab at ``url``, else blank, brought to the front, or with ``background`` behind the active tab, which
+        stays active, brought back only if the new tab took its place; its id. Headless, it opens blank and goes to
+        ``url`` once it's held to the window's size, so its page loads at that size."""
+        active = await self.active_tab() if background else None
         held = self.viewport is not None and url
         start = "about:blank" if held else url or "about:blank"
-        target = (await self.devtools.call("Target.createTarget", {"url": start}))["targetId"]
+        target = (await self.devtools.call("Target.createTarget", {"url": start, "background": background}))["targetId"]
         if held:
             await asyncio.wait_for(self._pinned.setdefault(target, asyncio.Event()).wait(), PIN_TIMEOUT_S)
             session = next(s for s, t in self._sessions.items() if t == target)
             await self.devtools.call("Page.navigate", {"url": url}, session_id=session)
-        await self._bring_to_front(target)
+        if not background:
+            await self._bring_to_front(target)
+        elif active is not None and active in self.tabs and await self.active_tab() == target:
+            await self._bring_to_front(active)
         return target
 
+    async def reopen_start_tabs(self, urls: list[str]) -> None:
+        """The start tabs at their ``urls`` again, in place, the first active: each tab open, in opened order, goes to
+        its URL, and any the browser lacks opens. A page already loaded doesn't read cookies set after it, so a tab
+        a load signed in shows it only once it loads again."""
+        tabs = list(self.tabs)
+        for index, url in enumerate(urls):
+            if index < len(tabs):
+                await self._navigate_tab(tabs[index], url)
+            else:
+                tabs.append(await self.open_tab(url))
+        if tabs:
+            await self._bring_to_front(tabs[0])
+
+    async def replace_tabs(self, tabs: list) -> None:
+        """``tabs``, each with its ``url`` and whether it's ``active``, opened in order in place of the tabs open now,
+        the active one, else the first, in front. The new ones open before the old close, so the window stays."""
+        before = list(self.tabs)
+        opened = [await self.open_tab(tab.url) for tab in tabs]
+        for target in before:
+            await self.close_tab(target)
+        if opened:
+            await self._bring_to_front(next((target for target, tab in zip(opened, tabs) if tab.active), opened[0]))
+
+    async def _navigate_tab(self, target: str, url: str) -> None:
+        session = next((s for s, t in self._sessions.items() if t == target), None)
+        if session is None:
+            raise DeviceUnavailable(f"the browser's tab {target} has no session to navigate it")
+        answer = await self.devtools.call("Page.navigate", {"url": url}, session_id=session)
+        if error := answer.get("errorText"):
+            raise InvalidArgument(f"the browser couldn't open {url}: {error}")
+
+    def forget(self) -> None:
+        """A record that starts now, as a reset leaves the browser: no tabs closed, downloads or dialogs before it, and
+        no origin seen."""
+        self.since = _now()
+        self.closed_tabs, self.dialog_log = [], []
+        self.downloads.clear()
+        self.origins.clear()
+
     async def activate(self, target: str) -> None:
         """The open tab ``target`` brought to the front, the active one."""
         self._open(target)