agentenv-framework-protocol 0.1.494__tar.gz → 0.1.496__tar.gz

{agentenv_framework_protocol-0.1.494 → agentenv_framework_protocol-0.1.496}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.494
+Version: 0.1.496
 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

{agentenv_framework_protocol-0.1.494 → agentenv_framework_protocol-0.1.496}/pyproject.toml

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

{agentenv_framework_protocol-0.1.494 → agentenv_framework_protocol-0.1.496}/src/agentenv_protocol/computer/app_data.py

@@ -1,7 +1,9 @@
 """An app's data plane as its own server serves it (``AppDataPlane``), by the app's data hooks or, with none, the
 defaults on the paths it keeps its data in, under the session user's home: a load writes the files it's given under
 them, an export returns the files there, and a reset puts back the copy its server kept when it first started on this
-boot, which is the app as installed, since every boot starts from the computer's image."""
+boot, which is the app as installed, since every boot starts from the computer's image. An export copies the files with
+the app paused, or, where the app holds one so that no other process may read it, as Windows lets an app hold a file
+and a pause doesn't release, with it stopped and relaunched after."""
 from __future__ import annotations
 
 import asyncio
@@ -17,7 +19,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 ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, FilePart, uploaded_object_path
 from .app_runtime import paused_app
 from .dataplane import data_files, file_parts, part_bytes
 
@@ -27,15 +29,24 @@ if TYPE_CHECKING:
 logger = logging.getLogger(__name__)
 
 #: The cause a launch after each data call logs.
-_CAUSES = {OP_ADD_DATA: METHOD_ADD, OP_RESET_DATA: METHOD_RESET}
+_CAUSES = {OP_ADD_DATA: METHOD_ADD, OP_GET_DATA: METHOD_GET, OP_RESET_DATA: METHOD_RESET}
 #: Where an app's server keeps its paths as installed, in the app's folder.
 INITIAL = Path(".agentenv/initial")
+#: Windows' errors for a file another process holds so that no other may read it: a sharing violation, and a lock on
+#: the part read.
+_HELD = (32, 33)
+
+
+class HeldByApp(OSError):
+    """A file under the app's paths that the running app holds so that no other process may read it, which stopping
+    the app releases and pausing it doesn't."""
 
 
 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, 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
+    reset, when the app says so; an export the app holds a file of (``HeldByApp``) stops it and relaunches it too. 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."""
 
@@ -90,7 +101,7 @@ class AppDataPlane:
             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)
+                result = await self._within_held(op, served, args, answer)
             except Exception:
                 if op == OP_ADD_DATA and self.resets_failed_add():
                     if op in self.live:
@@ -110,6 +121,24 @@ class AppDataPlane:
         else:
             answer.set_result(result)
 
+    async def _within_held(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
+        """``served``'s result within ``timeout_s``; where the app holds a file of its paths (``HeldByApp``), again with
+        the app stopped, in what's left of it, and the app relaunched after, as a load's is."""
+        loop = asyncio.get_running_loop()
+        deadline = loop.time() + self.timeout_s
+        try:
+            return await self._within(op, served, args, answer)
+        except HeldByApp:
+            stopped = await self.runtime.stop_app()
+        try:
+            result = await self._within(op, served, args, answer, deadline - loop.time())
+        finally:
+            if stopped:
+                await self.runtime.launch_app(_CAUSES[op])
+        if stopped and self.relaunched is not None:
+            await self.relaunched(op)
+        return result
+
     async def _undo(self, answer: asyncio.Future) -> None:
         """Reset the app's data after a load that failed."""
         if (reset := self._served(OP_RESET_DATA)) is None:
@@ -140,12 +169,14 @@ class AppDataPlane:
                 OP_GET_DATA: functools.partial(get, self.paths),
                 OP_RESET_DATA: functools.partial(reset, self.paths)}[op]
 
-    async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future) -> Any:
-        """``served``'s result within ``timeout_s``; past it, ``answer`` fails at once and the call is cancelled, and
-        this raises the same once it has ended: at once for what awaits, after any thread it runs."""
+    async def _within(self, op: str, served: Callable, args: tuple, answer: asyncio.Future,
+                      left_s: Optional[float] = None) -> Any:
+        """``served``'s result within ``left_s``, ``timeout_s`` by default; past it, ``answer`` fails at once and the
+        call is cancelled, and this raises the same once it has ended: at once for what awaits, after any thread it
+        runs."""
         work = asyncio.ensure_future(_called(served, *args))
         try:
-            return await asyncio.wait_for(asyncio.shield(work), self.timeout_s)
+            return await asyncio.wait_for(asyncio.shield(work), max(0.0, self.timeout_s if left_s is None else left_s))
         except TimeoutError:
             late = TimeoutError(f"{op} ran past the app's data_timeout_s, {self.timeout_s:g} s")
             if not answer.done():
@@ -185,11 +216,17 @@ async def add(parts: list, paths: list[str]) -> None:
 
 async def get(paths: list[str], write_namespace: Optional[WriteNamespaceGrant]) -> list:
     """A part for each file under ``paths``, copied with the app this server launched paused (``paused_app``), so they
-    are of one moment, and sent from the copy once it runs again; an app's own data/get hook calls it so too."""
+    are of one moment, and sent from the copy once it runs again; an app's own data/get hook calls it so too. A file
+    the paused app holds raises ``HeldByApp``, for its data plane to copy them with it stopped."""
     INITIAL.parent.mkdir(parents=True, exist_ok=True)
     with tempfile.TemporaryDirectory(dir=INITIAL.parent) as staging:
-        with paused_app():
-            await in_thread(_stage, Path.home(), paths, Path(staging))
+        try:
+            with paused_app():
+                await in_thread(_stage, Path.home(), paths, Path(staging))
+        except OSError as e:
+            if getattr(e, "winerror", None) in _HELD:
+                raise HeldByApp(f"the running app holds {e.filename or 'a file'} so that nothing else may read it") from e
+            raise
         return await file_parts(Path(staging), paths, write_namespace)
 
 

{agentenv_framework_protocol-0.1.494 → agentenv_framework_protocol-0.1.496}/tests/test_computer_app_data.py

@@ -2,8 +2,9 @@
 the defaults: a load writes files under them, through no link out of them, an export returns them, and a reset puts back
 the copy its server kept before it served; its card declares a file tree. Hooks override paths, and read the parts they
 get with part_bytes. Around a load and a reset the app is stopped and relaunched, a failed load is followed by a reset,
-and data calls take turns; an app that loads live is left running through a load, and a failed one is reset with it
-stopped, or left as it is when the app says so; an app with hooks may keep its paths as installed. A call past
+and data calls take turns; an export of a file the paused app holds stops it, copies it in what's left of its
+timeout, and relaunches it after; an app that loads live is left running through a load, and a failed one is reset
+with it stopped, or left as it is when the app says so; an app with hooks may keep its paths as installed. A call past
 data_timeout_s fails then and is cancelled, but a sync hook runs in a thread, which its reset and relaunch, and the next
 call, wait for. The app serves its skill file."""
 from __future__ import annotations
@@ -20,7 +21,7 @@ pytest.importorskip("mcp.server.fastmcp")
 
 import httpx  # noqa: E402
 
-from agentenv_protocol import add_data, client, reset_data  # noqa: E402
+from agentenv_protocol import add_data, client, get_data, reset_data  # noqa: E402
 from agentenv_protocol.agent_env_environment import OP_ADD_DATA  # noqa: E402
 from agentenv_protocol.computer import ComputerAppEnvironment, Launch, linux, part_bytes  # noqa: E402
 from agentenv_protocol.computer import app, app_data, app_runtime, session  # noqa: E402
@@ -106,8 +107,10 @@ def desktop(monkeypatch):
     @contextlib.contextmanager
     def paused(pid):
         events.append(("pause", pid))
-        yield
-        events.append(("continue", pid))
+        try:
+            yield
+        finally:
+            events.append(("continue", pid))
 
     monkeypatch.setattr(session, "launch", launch)
     monkeypatch.setattr(session, "stop", stop)
@@ -210,6 +213,32 @@ async def test_a_load_and_a_reset_stop_the_running_app_and_relaunch_it_and_an_ex
                        ("stop", 4244), ("launch", 4248)]
 
 
+@pytest.mark.asyncio
+async def test_an_export_of_a_file_the_paused_app_holds_stops_the_app_copies_it_and_relaunches_it(home, desktop,
+                                                                                                 monkeypatch):
+    """As Windows lets an app hold a file that no other process may read, which a pause doesn't release."""
+    (home / "Mail").mkdir()
+    (home / "Mail/inbox.txt").write_text("held")
+    mail = PathsMail()
+    mail._computer_app_data_plane().keep_initial()
+    await mail._computer_app.launch_app()
+    stage = app_data._stage
+
+    def held_while_running(*args):
+        if desktop[-1][0] == "pause":
+            held = PermissionError(13, "The process cannot access the file", str(home / "Mail/inbox.txt"))
+            held.winerror = 32
+            raise held
+        stage(*args)
+
+    monkeypatch.setattr(app_data, "_stage", held_while_running)
+    async with _http(mail) as http:
+        exported = _files(await _rpc(http, "data/get", {}))
+
+    assert [event[0] for event in desktop] == ["launch", "pause", "continue", "stop", "launch"]
+    assert desktop[3] == ("stop", 4242) and exported["Mail/inbox.txt"] == b"held"
+
+
 @pytest.mark.asyncio
 async def test_an_export_copies_the_paths_with_the_app_paused_and_sends_the_copy_once_it_runs_again(home, desktop,
                                                                                                   monkeypatch):
@@ -414,6 +443,32 @@ async def test_calls_take_turns_and_one_past_its_timeout_fails_then_while_what_f
                        ("launch", 4248), ("stop", 4248), ("load", 1), ("loaded", 1), ("launch", 4252)]
 
 
+@pytest.mark.asyncio
+async def test_an_export_retried_with_the_app_stopped_gets_only_what_is_left_of_its_timeout(home, desktop):
+    @linux(launch=Launch(command=["held"]))
+    class Held(ComputerAppEnvironment):
+        data_timeout_s = 1.0
+
+        @get_data
+        async def export(self) -> list:
+            if desktop[-1][0] == "launch":
+                await asyncio.sleep(0.8)
+                raise app_data.HeldByApp("the running app holds a file")
+            await asyncio.Event().wait()
+
+    held = Held()
+    await held._computer_app.launch_app()
+    started = time.monotonic()
+    async with _http(held) as http:
+        late = await http.post(RPC_PATH, json=_call("data/get", {}))
+    answered = time.monotonic() - started
+    await asyncio.gather(*held._computer_app_data_plane().changing)
+
+    assert late.json()["error"]["message"] == "get_data ran past the app's data_timeout_s, 1 s"
+    assert answered < 1.5
+    assert desktop == [("launch", 4242), ("stop", 4242), ("launch", 4244)]
+
+
 @pytest.mark.asyncio
 async def test_it_serves_its_skill_file_and_no_skill_without_one(home, tmp_path):
     (tmp_path / "folder" / "SKILL.md").write_text("---\ndescription: Reading and sending mail.\n---\n\n# Mail\nUse it.\n")