agentenv-framework-protocol 0.1.391__tar.gz → 0.1.392__tar.gz

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.391
+Version: 0.1.392
 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
@@ -293,6 +293,32 @@ at the gateway.
 
 Where the binding lives depends on the app. On mcp's own FastMCP it wraps the tool manager's dispatch; on the standalone `fastmcp` package it joins the app's middleware chain as the outermost layer, so a handler's own middleware runs under it too. An app with neither seam mounts unbound, with a warning, unless a tool declares a `ToolContext` parameter or the handler defines `on_tool_call`: then the mount is refused rather than serving an empty caller.
 
+### Getting part of the data
+
+A `@get_data` handler that takes a `paths` parameter returns only the data under the paths a caller
+names (`client.get_data(base_url, paths=[...])`), and is called with None when the caller names
+none. A handler without one answers `invalid_params` to a call that names paths, rather than
+returning everything.
+
+### A skill for agents
+
+An env can hand agents a skill: a SKILL.md an agent reads before it uses the env. Mark the method
+that writes it with `@agent_skill`; it returns the skill's description and its markdown body,
+sync or async:
+
+```python
+@agent_skill
+def guide(self):
+    return "How to place and track orders.", "# The shop\n\nPlace orders with `place_order`.\n"
+```
+
+The card then declares `urn:agentenv:skill/v1` (`SKILL_EXTENSION_URI`), whose `get {name}`
+answers `{name, description, skill_md}`, the shape `skill-config/v1` takes, with the frontmatter
+written under the name the caller gives; a name that isn't lowercase letters, digits and single
+hyphens, up to 64, is refused `invalid_argument`. agent-env's `add_skills` step installs it on
+an agent through `env_ids`, named after the env's environment name; for an env behind a gateway,
+whose card nests its servers' cards, it installs each server's skill under that server's name.
+
 ### Uploading an export through a grant
 
 An export too large to return from `data/get` can go straight to the caller's object store. A
@@ -449,6 +475,11 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   (`stale_frame`) when the display geometry it was captured at changes.
 - **The input queue.** Input calls run one at a time in arrival order; one that waits past
   `queue_wait_s` is refused `input_busy`. Screenshots and waits never queue.
+- **The computer skill.** `computer/v1` declares the seven tools, its params the driver's
+  features. The driver serves its skill through `skill/v1` (an `@agent_skill` handler on the base
+  class): a SKILL.md written from the computer as it booted (its platform, session user and home,
+  the live screen size, what its input takes, its OS's shortcuts) and ending with the driver
+  class's `notes`, markdown for what its card can't say.
 - **Framework extensions.** `computer-ready/v1` (`status`: real checks of the display and a
   capture, plus the driver's own `ready_checks()`; tools refuse `device_unavailable` until they
   pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
@@ -458,8 +489,10 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
 - **The data plane.** `data/add` takes file parts that name their path, relative to the session
   user's home, under the `data-objects/v1` marker (`{"path": ...}`), as inline bytes, an https URL,
   or a `transfers.ReadObject` read grant under the marker's `read`, and writes them atomically.
-  `data/get` returns the files under the settings' `data_paths`, inline or uploaded under a
-  `write_namespace` grant.
+  `data/get` returns the files under the `paths` it's given, relative to the home, or under the
+  card's `default_data_paths` (`Desktop`, `Documents`, `Downloads`) when it's given none, inline or
+  uploaded under a `write_namespace` grant. An environment whose `@get_data` hook takes no `paths`
+  refuses them.
 - **The card** (the name from `ENVIRONMENT_NAME`, then `@computer_driver`'s), and per-role tool
   access (`tool_access` is on).
 
@@ -470,7 +503,7 @@ was sent (`applied: "no"`); `Timeout`, `DeliveryFailed` and `Internal` mean it m
 other exception from an input operation is reported `delivery_failed` with `applied: "unknown"`.
 
 **Settings** reach the driver as one JSON value in `AGENTENV_COMPUTER_SETTINGS`
-(`ComputerSettings`): `data_paths`, `default_space`, `default_norm_scale`, `queue_wait_s`,
+(`ComputerSettings`): `default_space`, `default_norm_scale`, `queue_wait_s`,
 `tap_hold_ms`, `type_delay_ms`, `max_hold_ms`, `layout`, `drag_duration_ms`, `exec_output_bytes`
 and `exec_timeout_s`. A driver reads them as `self.settings`, for example its tap hold in `@press`.
 
@@ -509,13 +542,16 @@ class MyDriver(ComputerDriverEnvironment):
   `@pointer_position`: the slow path, at most 15 fps.
 - **The methods.** `start {request_id, scope?, fps?, max_edge?, cursor?, upload?}` returns
   `{recording_id, started_at, format}`; `end {recording_id, upload?, reason?}` closes the last segment
-  and returns the manifest. A repeated `request_id`, or a repeated `end`, answers the same. A start
-  past `max_concurrent` is refused `limit_exceeded`; `max_duration_s`, free disk under 512 MB or a stream
+  and returns the manifest; `end_all {reason?}` ends every recording not yet ended, each under the
+  grant it started with, and returns `{manifests}`, as the framework does before it resets or tears a
+  computer down. A repeated `request_id`, or a repeated `end`, answers the same. A start past
+  `max_concurrent` is refused `limit_exceeded`; `max_duration_s`, free disk under 512 MB or a stream
   failing for 60 s end a recording by itself.
 - **Segments.** A segment closes at `max_segment_s`, when the frame size changes or after a gap in the
   stream. Each uploads as it closes under `start`'s `write_namespace` grant, at
   `<recording_id>/<index>.mp4`, and is then deleted; `end`'s own grant uploads any that missed. With no
-  grant they stay under `~/.agentenv-recordings/`.
+  grant they stay under `~/.agentenv-recordings/`. An ended recording's manifest uploads beside its
+  segments, at `<recording_id>/manifest.json`, so a reader that didn't end it finds it there.
 - **The manifest** (`RecordingManifest`). Its `segments` (`ManifestSegment`) carry each one's path,
   `started_at` and `ended_at` (its first and last frames' capture times), size, frame count, byte size,
   SHA-256 and whether it uploaded, and `ended_by` says why the recording ended: `end`, `reset`,

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/README.md

@@ -240,6 +240,32 @@ at the gateway.
 
 Where the binding lives depends on the app. On mcp's own FastMCP it wraps the tool manager's dispatch; on the standalone `fastmcp` package it joins the app's middleware chain as the outermost layer, so a handler's own middleware runs under it too. An app with neither seam mounts unbound, with a warning, unless a tool declares a `ToolContext` parameter or the handler defines `on_tool_call`: then the mount is refused rather than serving an empty caller.
 
+### Getting part of the data
+
+A `@get_data` handler that takes a `paths` parameter returns only the data under the paths a caller
+names (`client.get_data(base_url, paths=[...])`), and is called with None when the caller names
+none. A handler without one answers `invalid_params` to a call that names paths, rather than
+returning everything.
+
+### A skill for agents
+
+An env can hand agents a skill: a SKILL.md an agent reads before it uses the env. Mark the method
+that writes it with `@agent_skill`; it returns the skill's description and its markdown body,
+sync or async:
+
+```python
+@agent_skill
+def guide(self):
+    return "How to place and track orders.", "# The shop\n\nPlace orders with `place_order`.\n"
+```
+
+The card then declares `urn:agentenv:skill/v1` (`SKILL_EXTENSION_URI`), whose `get {name}`
+answers `{name, description, skill_md}`, the shape `skill-config/v1` takes, with the frontmatter
+written under the name the caller gives; a name that isn't lowercase letters, digits and single
+hyphens, up to 64, is refused `invalid_argument`. agent-env's `add_skills` step installs it on
+an agent through `env_ids`, named after the env's environment name; for an env behind a gateway,
+whose card nests its servers' cards, it installs each server's skill under that server's name.
+
 ### Uploading an export through a grant
 
 An export too large to return from `data/get` can go straight to the caller's object store. A
@@ -396,6 +422,11 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   (`stale_frame`) when the display geometry it was captured at changes.
 - **The input queue.** Input calls run one at a time in arrival order; one that waits past
   `queue_wait_s` is refused `input_busy`. Screenshots and waits never queue.
+- **The computer skill.** `computer/v1` declares the seven tools, its params the driver's
+  features. The driver serves its skill through `skill/v1` (an `@agent_skill` handler on the base
+  class): a SKILL.md written from the computer as it booted (its platform, session user and home,
+  the live screen size, what its input takes, its OS's shortcuts) and ending with the driver
+  class's `notes`, markdown for what its card can't say.
 - **Framework extensions.** `computer-ready/v1` (`status`: real checks of the display and a
   capture, plus the driver's own `ready_checks()`; tools refuse `device_unavailable` until they
   pass once), `computer-display/v1`, `computer-spaces/v1` (the default space, written into the tool
@@ -405,8 +436,10 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
 - **The data plane.** `data/add` takes file parts that name their path, relative to the session
   user's home, under the `data-objects/v1` marker (`{"path": ...}`), as inline bytes, an https URL,
   or a `transfers.ReadObject` read grant under the marker's `read`, and writes them atomically.
-  `data/get` returns the files under the settings' `data_paths`, inline or uploaded under a
-  `write_namespace` grant.
+  `data/get` returns the files under the `paths` it's given, relative to the home, or under the
+  card's `default_data_paths` (`Desktop`, `Documents`, `Downloads`) when it's given none, inline or
+  uploaded under a `write_namespace` grant. An environment whose `@get_data` hook takes no `paths`
+  refuses them.
 - **The card** (the name from `ENVIRONMENT_NAME`, then `@computer_driver`'s), and per-role tool
   access (`tool_access` is on).
 
@@ -417,7 +450,7 @@ was sent (`applied: "no"`); `Timeout`, `DeliveryFailed` and `Internal` mean it m
 other exception from an input operation is reported `delivery_failed` with `applied: "unknown"`.
 
 **Settings** reach the driver as one JSON value in `AGENTENV_COMPUTER_SETTINGS`
-(`ComputerSettings`): `data_paths`, `default_space`, `default_norm_scale`, `queue_wait_s`,
+(`ComputerSettings`): `default_space`, `default_norm_scale`, `queue_wait_s`,
 `tap_hold_ms`, `type_delay_ms`, `max_hold_ms`, `layout`, `drag_duration_ms`, `exec_output_bytes`
 and `exec_timeout_s`. A driver reads them as `self.settings`, for example its tap hold in `@press`.
 
@@ -456,13 +489,16 @@ class MyDriver(ComputerDriverEnvironment):
   `@pointer_position`: the slow path, at most 15 fps.
 - **The methods.** `start {request_id, scope?, fps?, max_edge?, cursor?, upload?}` returns
   `{recording_id, started_at, format}`; `end {recording_id, upload?, reason?}` closes the last segment
-  and returns the manifest. A repeated `request_id`, or a repeated `end`, answers the same. A start
-  past `max_concurrent` is refused `limit_exceeded`; `max_duration_s`, free disk under 512 MB or a stream
+  and returns the manifest; `end_all {reason?}` ends every recording not yet ended, each under the
+  grant it started with, and returns `{manifests}`, as the framework does before it resets or tears a
+  computer down. A repeated `request_id`, or a repeated `end`, answers the same. A start past
+  `max_concurrent` is refused `limit_exceeded`; `max_duration_s`, free disk under 512 MB or a stream
   failing for 60 s end a recording by itself.
 - **Segments.** A segment closes at `max_segment_s`, when the frame size changes or after a gap in the
   stream. Each uploads as it closes under `start`'s `write_namespace` grant, at
   `<recording_id>/<index>.mp4`, and is then deleted; `end`'s own grant uploads any that missed. With no
-  grant they stay under `~/.agentenv-recordings/`.
+  grant they stay under `~/.agentenv-recordings/`. An ended recording's manifest uploads beside its
+  segments, at `<recording_id>/manifest.json`, so a reader that didn't end it finds it there.
 - **The manifest** (`RecordingManifest`). Its `segments` (`ManifestSegment`) carry each one's path,
   `started_at` and `ended_at` (its first and last frames' capture times), size, frame count, byte size,
   SHA-256 and whether it uploaded, and `ended_by` says why the recording ended: `end`, `reset`,

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/pyproject.toml

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

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/__init__.py

@@ -12,6 +12,7 @@ from .agent_env_environment import (
     AgentEnvFastMCPApplication,
     AgentEnvStarletteApplication,
     add_data,
+    agent_skill,
     create_fastmcp_app,
     environment_card,
     extension,
@@ -58,6 +59,7 @@ from .types import (
     METHOD_RESET,
     PROTOCOL_VERSION,
     RPC_PATH,
+    SKILL_EXTENSION_URI,
     WELL_KNOWN_PATH,
     AddDataRequest,
     AddDataResponse,
@@ -91,6 +93,7 @@ __all__ = [
     "reset_data",
     "add_data",
     "get_data",
+    "agent_skill",
     "extension",
     "tool",
     "injecting",
@@ -117,6 +120,7 @@ __all__ = [
     "intake_fit_check",
     "INTAKE_EXTENSION_URI",
     "DATA_OBJECTS_EXTENSION_URI",
+    "SKILL_EXTENSION_URI",
     "uploaded_file_part",
     "uploaded_object_path",
     "MCP_PATH",

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/agent_env_environment.py

@@ -9,6 +9,7 @@ import inspect
 import json
 import logging
 import os
+import re
 import sys
 import types
 import uuid
@@ -26,7 +27,7 @@ from .tool_access import DISABLE as TOOL_DISABLE, ENABLE as TOOL_ENABLE, PATHS a
 from .tool_access import extensions as tool_access_extensions
 from .tool_context import EMPTY, ToolContext, bound, context_from_http, context_from_mcp
 from .transfers import WriteNamespaceGrant
-from .types import DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body
+from .types import DATA_OBJECTS_EXTENSION_URI, MCP_TRANSPORT, SKILL_EXTENSION_URI, METHOD_ADD, METHOD_GET, METHOD_RESET, RPC_PATH, WELL_KNOWN_PATH, AddDataRequest, AddDataResponse, EnvironmentCapabilities, EnvironmentCard, EnvironmentExtension, EnvironmentInterface, EnvironmentTool, GetDataResponse, ResetDataResponse, error_body
 
 logger = logging.getLogger(__name__)
 
@@ -53,6 +54,7 @@ RPC_ERROR_CODE_INVALID_REQUEST = -32600
 RPC_ERROR_CODE_METHOD_NOT_FOUND = -32601
 RPC_ERROR_CODE_INVALID_PARAMS = -32602
 RPC_ERROR_CODE_SERVER_ERROR = -32000
+_SKILL_NAME = re.compile(r"[a-z0-9]+(-[a-z0-9]+)*")
 
 
 def reset_data(fn: Callable) -> Callable:
@@ -126,6 +128,23 @@ def extension(uri: str, *, op: str | None = None, description: str | None = None
     return deco
 
 
+def agent_skill(fn: Callable) -> Callable:
+    """Mark the method that writes this env's skill for agents, returning its description and its markdown body; it
+    is served under ``SKILL_EXTENSION_URI`` as ``get {name}``, which writes the SKILL.md under the name asked for."""
+
+    async def get(self, name: str) -> dict:
+        if len(name) > 64 or not _SKILL_NAME.fullmatch(name):
+            raise AgentEnvError("invalid_argument",
+                                f"a skill's name is lowercase letters, digits and single hyphens, up to 64, not {name!r}")
+        description, body = await fn(self) if inspect.iscoroutinefunction(fn) else fn(self)
+        frontmatter = f"---\nname: {name}\ndescription: {json.dumps(description)}\n---\n"
+        return {"name": name, "description": description, "skill_md": f"{frontmatter}\n{body}"}
+
+    get.__name__ = fn.__name__
+    return extension(SKILL_EXTENSION_URI, op="get", method="GET",
+                     description="get returns a SKILL.md for agents under the name it's given.")(get)
+
+
 def _extension_slug(uri: str) -> str:
     """``urn:agentenv:computer-display/v1`` -> ``computer-display``; another namespace keeps its name as a path."""
     name = uri.removeprefix("urn:").removeprefix("agentenv:")
@@ -1162,6 +1181,14 @@ async def _invoke_add(fn: Callable, params: dict) -> dict:
 
 async def _invoke_get(fn: Callable, params: dict) -> dict:
     kwargs = {}
+    takes_paths = "paths" in inspect.signature(fn).parameters
+    if isinstance(params, dict) and "paths" in params:
+        if not takes_paths:
+            raise _InvalidParams("data/get on this environment takes no paths: it returns all of its data")
+        if not isinstance(params["paths"], list) or not all(isinstance(path, str) for path in params["paths"]):
+            raise _InvalidParams("paths must be a list of strings")
+    if takes_paths:
+        kwargs["paths"] = params.get("paths") if isinstance(params, dict) else None
     if _takes_write_namespace(fn):
         if not isinstance(params, dict):
             raise _InvalidParams("data/get takes its params by name")

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/client.py

@@ -57,11 +57,15 @@ async def add_data(base_url: str, parts: list[Part], timeout: int = 120, verify:
 
 
 async def get_data(
-    base_url: str, timeout: int = 30, verify: bool = True, *, write_namespace: WriteNamespaceGrant | None = None
+    base_url: str, timeout: int = 30, verify: bool = True, *, write_namespace: WriteNamespaceGrant | None = None,
+    paths: list[str] | None = None,
 ) -> GetDataResponse:
     """`data/get`. A server advertising `DATA_OBJECTS_EXTENSION_URI` may be handed `write_namespace` to upload
-    its export under; `uploaded_object_path` reads from the answer where it did."""
+    its export under; `uploaded_object_path` reads from the answer where it did. `paths` names what a computer
+    returns, relative to its user's home; an env that returns all of its data refuses them."""
     params = {} if write_namespace is None else {"write_namespace": write_namespace.model_dump(mode="json", exclude_none=True)}
+    if paths is not None:
+        params["paths"] = paths
     return GetDataResponse.model_validate(await _rpc(base_url, METHOD_GET, params, timeout, verify))
 
 

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/_declare.py

@@ -77,7 +77,8 @@ def declare(folder: Path, file: str, name: str) -> dict:
     return {"name": cards[0][1].name, "supports": list(cls.supports), "platforms": [
         {"platform": platform.as_dict(), "provides": [e.uri for e in card.capabilities.extensions],
          "tools": [t.name for t in card.capabilities.tools],
-         "features": next(e.params for e in card.capabilities.extensions if e.uri == COMPUTER)}
+         "features": next({k: v for k, v in e.params.items() if k not in ("endpoint", "methods")}
+                          for e in card.capabilities.extensions if e.uri == COMPUTER)}
         for platform, card in cards]}
 
 

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/card.py

@@ -1,10 +1,11 @@
 """What a driver's card says: the extensions, the tools, extensions and data-plane methods its operations support,
-the extensions' params, the extensions it declares without handlers, and the descriptions that name the default
-coordinate space."""
+the extensions' params (computer/v1's are the driver's features), the extensions it declares without handlers, and the
+descriptions that name the default coordinate space."""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING
 
+from .dataplane import DEFAULT_DATA_PATHS
 from .recording import recording_params
 from ..types import METHOD_ADD, EnvironmentExtension, EnvironmentTool, IntakeDeclaration, IntakeFormat, intake_extension
 
@@ -79,18 +80,23 @@ def extension_params(driver: ComputerDriverEnvironment, uri: str) -> dict:
     return {}
 
 
-def declared_extensions(driver: ComputerDriverEnvironment) -> list[EnvironmentExtension]:
-    features = {
+def computer_features(driver: ComputerDriverEnvironment) -> dict:
+    """computer/v1's params: what the seven tools take, how input is delivered, the platform and the default data
+    paths."""
+    return {
         "buttons": list(driver.buttons), "max_click_count": driver.max_click_count,
         "keys": driver.keys if driver.keys == "all" else list(driver.keys), "max_text_length": driver.max_text_length,
         "max_wait_ms": driver.max_wait_ms, "max_drag_points": driver.max_drag_points,
         "max_duration_ms": driver.max_duration_ms, "max_key_repeat": driver.max_key_repeat,
-        "max_scroll_amount": driver.max_scroll_amount,
+        "max_scroll_amount": driver.max_scroll_amount, "delivery": "foreground", "platform": driver.platform.as_dict(),
+        "supports": list(driver.supports), "default_data_paths": list(DEFAULT_DATA_PATHS),
     }
+
+
+def declared_extensions(driver: ComputerDriverEnvironment) -> list[EnvironmentExtension]:
     declared = [EnvironmentExtension(
         uri=COMPUTER, description="The seven computer_* tools: screenshot, click, drag, scroll, type, key, wait.",
-        params={**features, "delivery": "foreground", "platform": driver.platform.as_dict(),
-                "supports": list(driver.supports)})]
+        params=computer_features(driver))]
     if driver.has("pointer"):
         declared.append(EnvironmentExtension(
             uri=COMPUTER_POINTER, description="The computer_pointer_* tools, and click and scroll at the pointer.",
@@ -99,7 +105,7 @@ def declared_extensions(driver: ComputerDriverEnvironment) -> list[EnvironmentEx
     if driver.has("write_files"):
         intake.add = [IntakeFormat(part="file", format="file-tree", load="additive")]
     declared.append(intake_extension(intake, "data/add writes files under the session user's home; data/get "
-                                             "returns the env's data paths."))
+                                             "returns those under the paths it's given, or the default data paths."))
     return declared
 
 

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/conformance/checks.py

@@ -21,7 +21,7 @@ from pydantic import ValidationError
 from ... import client as protocol
 from ...client import ExtensionCallError
 from ...tool_access import DISABLE_TOOL_EXTENSION_URI, ENABLE_TOOL_EXTENSION_URI
-from ...types import DATA_OBJECTS_EXTENSION_URI, INTAKE_EXTENSION_URI
+from ...types import DATA_OBJECTS_EXTENSION_URI, INTAKE_EXTENSION_URI, SKILL_EXTENSION_URI
 from ..card import (
     COMPUTER,
     COMPUTER_DISPLAY,
@@ -88,7 +88,7 @@ class Probe:
         for check, section in (("P0", self._ready), ("P1", self._card), ("P2", self._frame), ("P5", self._refusals),
                                ("X", self._display), ("X", self._spaces), ("X", self._keyboard_settings),
                                ("X", self._exec), ("X", self._data_get), ("X", self._tool_access),
-                               ("X", self._pointer)):
+                               ("X", self._pointer), ("X", self._skill)):
             await self._guarded(check, section)
         self._grants()
 
@@ -388,6 +388,18 @@ class Probe:
             await self.check("X", "output past max_output_bytes is cut there", capped, COMPUTER_EXEC)
         await self.check("X", "a program that isn't there is refused with a code", missing, COMPUTER_EXEC)
 
+    async def _skill(self) -> None:
+        if not self.driver.declares(SKILL_EXTENSION_URI):
+            return
+
+        async def written() -> str | None:
+            got = await self.driver.invoke(SKILL_EXTENSION_URI, "get", {"name": "probe-skill"})
+            if got.get("name") != "probe-skill" or not str(got.get("skill_md")).startswith("---\nname: probe-skill\n"):
+                return f"it answered {got}"
+            return None if got.get("description") else "its description is empty"
+
+        await self.check("X", "the skill is written under the name it's asked for", written, SKILL_EXTENSION_URI)
+
     async def _data_get(self) -> None:
         if not self.driver.declares(INTAKE_EXTENSION_URI):
             return

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/dataplane.py

@@ -1,5 +1,6 @@
 """The data plane on a computer: ``data/add`` writes files under the session user's home, ``data/get`` returns the
-env's ``data_paths``. Each file part names its path, relative to the home, under the ``data-objects/v1`` marker."""
+files under the paths its caller names, or under ``DEFAULT_DATA_PATHS`` when it names none. Each file part names its
+path, relative to the home, under the ``data-objects/v1`` marker."""
 from __future__ import annotations
 
 import base64
@@ -10,10 +11,10 @@ from pathlib import Path
 from typing import TYPE_CHECKING, Optional
 
 import httpx
-from pydantic import ValidationError
+from pydantic import TypeAdapter, ValidationError
 
 from ..agent_env_environment import add_data, get_data
-from ..transfers import NamespaceUploader, ReadObject, WriteNamespaceGrant, download
+from ..transfers import NamespaceUploader, ReadObject, RelativePath, WriteNamespaceGrant, download
 from ..types import DATA_OBJECTS_EXTENSION_URI, FilePart, FileWithBytes, FileWithUri, uploaded_file_part, uploaded_object_path
 
 if TYPE_CHECKING:
@@ -22,6 +23,9 @@ if TYPE_CHECKING:
 
 #: The most an https URL part may fetch; a read grant carries its own limit.
 MAX_URL_BYTES = 1 << 30
+#: What ``data/get`` returns when its caller names no paths: the folders a desktop keeps its user's files in.
+DEFAULT_DATA_PATHS = ("Desktop", "Documents", "Downloads")
+_PATHS = TypeAdapter(list[RelativePath])
 
 
 class DataPlane:
@@ -47,8 +51,13 @@ class DataPlane:
         await self._computer.call("write_files", files)
 
     @get_data
-    async def _computer_data_get(self, write_namespace: Optional[WriteNamespaceGrant] = None) -> list:
-        files = _data_files(Path.home(), self.settings.data_paths)
+    async def _computer_data_get(self, write_namespace: Optional[WriteNamespaceGrant] = None,
+                                 paths: Optional[list[str]] = None) -> list:
+        try:
+            named = _PATHS.validate_python(paths) if paths is not None else list(DEFAULT_DATA_PATHS)
+        except ValidationError:
+            raise ValueError(f"data/get on a computer takes paths relative to the home, not {paths!r}") from None
+        files = _data_files(Path.home(), named)
         if write_namespace is not None:
             uploader = NamespaceUploader(write_namespace)
             parts = []
@@ -98,11 +107,11 @@ async def _get_url(file: FileWithUri) -> bytes:
     return bytes(data)
 
 
-def _data_files(home: Path, data_paths: list[str]) -> list[tuple[str, Path]]:
-    """Every file under the data paths, by its path relative to the home; a path not there yet is skipped."""
+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] = {}
-    for relative in data_paths:
+    for relative in paths:
         target = home / relative
         if not target.exists() or not target.resolve().is_relative_to(root):
             continue

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/driver.py

@@ -46,6 +46,8 @@ class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironmen
     #: computer-recording/v1, from ``@record`` if the driver has one, else by polling ``@capture``; ``None`` turns
     #: it off.
     recording: ClassVar[Recording | None] = Recording()
+    #: What an agent should know about this driver's computer beyond what its card says, as markdown: the end of its skill.
+    notes: ClassVar[str] = ""
     tool_access = True
     #: What the base class keeps for the driver, built by ``__init__``.
     _computer: ComputerRuntime | None = None

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/extensions.py

@@ -1,10 +1,10 @@
-"""The framework extensions agentenv calls, never agents: readiness, display, coordinate spaces, keyboard settings,
-commands in the session and recordings."""
+"""The framework extensions agentenv calls, never agents: the computer skill, readiness, display, coordinate spaces,
+keyboard settings, commands in the session and recordings."""
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Callable, Optional
 
-from ..agent_env_environment import extension
+from ..agent_env_environment import agent_skill, extension
 from . import card
 from .card import (
     COMPUTER_DISPLAY,
@@ -18,6 +18,7 @@ from .card import (
 )
 from .errors import Internal, InvalidArgument, Unsupported
 from .operations import Display, ExecResult
+from .skill import skill
 from .spaces import check_space
 
 if TYPE_CHECKING:
@@ -36,6 +37,10 @@ class Extensions:
     layouts: tuple[str, ...]
     mounted_card: Callable[[], EnvironmentCard]
 
+    @agent_skill
+    async def _computer_skill(self) -> tuple[str, str]:
+        return await skill(self)
+
     @extension(COMPUTER_READY, op="status", method="GET",
                description="Whether the computer is usable now, by real checks; never sends input.")
     async def _computer_ready_status(self) -> dict:
@@ -114,7 +119,8 @@ class Extensions:
 
     @extension(COMPUTER_RECORDING, op="start",
                description="Record the display: start returns a recording whose segments upload through its grant as "
-                           "they close, and end seals it and returns its manifest; repeats answer the same.")
+                           "they close; end seals it and returns its manifest, uploaded beside them; end_all ends "
+                           "every one not yet ended; repeats answer the same.")
     async def _computer_recording_start(self, request_id: str, scope: str = "display", window: Optional[str] = None,
                                         fps: Optional[int] = None, max_edge: Optional[int] = None, cursor: bool = True,
                                         upload: Optional[dict] = None) -> dict:
@@ -125,6 +131,10 @@ class Extensions:
                                       reason: str = "end") -> dict:
         return await self._computer.recordings.end(recording_id, upload, reason)
 
+    @extension(COMPUTER_RECORDING, op="end_all")
+    async def _computer_recording_end_all(self, reason: str = "end") -> dict:
+        return {"manifests": await self._computer.recordings.end_all(reason)}
+
 
 async def _run(computer: ComputerRuntime, cap: int, argv: list, cwd: Optional[str], env: Optional[dict],
                timeout: float) -> dict:

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/recording.py

@@ -7,6 +7,7 @@ import asyncio
 import contextlib
 import dataclasses
 import hashlib
+import json
 import shutil
 import threading
 import time
@@ -38,6 +39,8 @@ MP4 = "video/mp4; codecs=avc1"
 RECORDINGS_DIR = ".agentenv-recordings"
 SCOPES = ("display", "window")
 REASONS = ("end", "reset", "teardown")
+#: What an ended recording's manifest is uploaded as, under its id beside its segments.
+MANIFEST = "manifest.json"
 DEFAULT_FPS = 10
 #: The fallback polls ``@capture``, a full read of the screen each pass, so it is capped lower than streams.
 MAX_POLLED_FPS = 15
@@ -179,6 +182,10 @@ class Recordings:
             self.ended.popitem(last=False)
         return manifest
 
+    async def end_all(self, reason: str) -> list[dict]:
+        """End every recording not yet ended, each uploading under the grant it was started with; their manifests."""
+        return [await self.end(recording_id, None, reason) for recording_id in list(self.running)]
+
     def _hints(self, features: Recording, scope: str, window: Optional[str], fps: Optional[int],
                max_edge: Optional[int], cursor: bool, upload: Optional[dict]) -> tuple[RecordHints, Any]:
         if scope not in SCOPES:
@@ -287,11 +294,15 @@ class _Recording:
         with contextlib.suppress(OSError):
             self.hints.directory.rmdir()
         entries = [s.entry for s in self.segments]
-        return RecordingManifest(
+        manifest = RecordingManifest(
             recording_id=self.id, scope=self.hints.scope, format=MP4, fps=self.hints.fps, cursor=self.cursor,
             source="stream" if self.streams else "capture", started_at=entries[0].started_at if entries else None,
             ended_at=entries[-1].ended_at if entries else None, ended_by=self.ended_by, segments=entries,
             error=self.error if self.ended_by == "error" else None).wire()
+        if uploader is not None:  # beside the segments, so a reader who didn't end the recording finds it
+            with contextlib.suppress(Exception):
+                await uploader.upload(f"{self.id}/{MANIFEST}", json.dumps(manifest).encode())
+        return manifest
 
     async def _add_frame(self, item: RecordedFrame) -> None:
         frame = await self._in_thread(_video_frame, item.image, self.hints.max_edge)

{agentenv_framework_protocol-0.1.391 → agentenv_framework_protocol-0.1.392}/src/agentenv_protocol/computer/settings.py

@@ -7,7 +7,6 @@ from typing import Literal
 
 from pydantic import BaseModel, ConfigDict, Field, ValidationError
 
-from ..transfers import RelativePath
 
 SETTINGS_ENV = "AGENTENV_COMPUTER_SETTINGS"
 
@@ -15,12 +14,10 @@ Space = Literal["frame", "norm"]
 
 
 class ComputerSettings(BaseModel):
-    """``data_paths`` are relative to the session user's home and are what ``data/get`` returns; the rest are the
-    defaults the card reports and the framework extensions change."""
+    """The defaults the card reports and the framework extensions change."""
 
     model_config = ConfigDict(extra="forbid", validate_assignment=True)
 
-    data_paths: list[RelativePath] = Field(default_factory=list)
     default_space: Space = "frame"
     default_norm_scale: int = Field(default=1000, ge=1, le=1_000_000)
     queue_wait_s: float = Field(default=30.0, gt=0, le=3600)