agentenv-framework-protocol 0.1.418__tar.gz → 0.1.420__tar.gz

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.418
+Version: 0.1.420
 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
@@ -561,8 +561,8 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   or a `transfers.ReadObject` read grant under the marker's `read`, and writes them atomically.
   `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.
+  uploaded under a `write_namespace` grant, leaving out the paths its apps keep their data in. 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).
 
@@ -730,8 +730,10 @@ class MailApp(ComputerAppEnvironment):
   naming one the app declares no install for is refused when the class is read. A step reads
   `self.build_settings`; a deploy's `self.settings` aren't known at build, and reading one raises
   `AttributeError` (`python -m agentenv_protocol.computer.run_install_step <file>:<Class> <method>`).
-- **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both;
-  its data hooks are the usual `@add_data`, `@get_data` and `@reset_data`.
+- **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both.
+- **Its data** is under the `paths` its OS's decorator names, relative to the session user's home,
+  none inside another (`@linux(..., paths=["Mail", ".config/mail/accounts.json"])`), or what its own
+  `@add_data`, `@get_data` and `@reset_data` hooks serve instead (below).
 - **`Settings`** is typed; a computer hands each app the values a deploy gives it, as one JSON value
   in `APP_SETTINGS_ENV` (`AGENTENV_APP_SETTINGS`, the apps' values by name), and the base class reads
   its own, by `ENVIRONMENT_NAME`, as `self.settings`. A `SecretStr` field is a secret.
@@ -757,6 +759,18 @@ folder: the computer is ready once every app's server answers and each `boot` ap
 no launch, says it's ready; a `demand` app counts once something launches it. What the server does
 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
+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:
+its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
+requests to the app's server.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores, 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.

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/README.md

@@ -505,8 +505,8 @@ driver has them, through the `served_tools`, `served_extensions` and `served_ope
   or a `transfers.ReadObject` read grant under the marker's `read`, and writes them atomically.
   `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.
+  uploaded under a `write_namespace` grant, leaving out the paths its apps keep their data in. 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).
 
@@ -674,8 +674,10 @@ class MailApp(ComputerAppEnvironment):
   naming one the app declares no install for is refused when the class is read. A step reads
   `self.build_settings`; a deploy's `self.settings` aren't known at build, and reading one raises
   `AttributeError` (`python -m agentenv_protocol.computer.run_install_step <file>:<Class> <method>`).
-- **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both;
-  its data hooks are the usual `@add_data`, `@get_data` and `@reset_data`.
+- **Its skill** is a file of its folder (`skill = "skill.md"`) or an `@agent_skill` method, not both.
+- **Its data** is under the `paths` its OS's decorator names, relative to the session user's home,
+  none inside another (`@linux(..., paths=["Mail", ".config/mail/accounts.json"])`), or what its own
+  `@add_data`, `@get_data` and `@reset_data` hooks serve instead (below).
 - **`Settings`** is typed; a computer hands each app the values a deploy gives it, as one JSON value
   in `APP_SETTINGS_ENV` (`AGENTENV_APP_SETTINGS`, the apps' values by name), and the base class reads
   its own, by `ENVIRONMENT_NAME`, as `self.settings`. A `SecretStr` field is a secret.
@@ -701,6 +703,18 @@ folder: the computer is ready once every app's server answers and each `boot` ap
 no launch, says it's ready; a `demand` app counts once something launches it. What the server does
 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
+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:
+its card lists each one's card as a child environment, rooted at `/svc/<app>/`, where it forwards
+requests to the app's server.
+
 `MailApp.declaration()` returns what the class declares, an `AppDeclaration`, which a `computer_app`
 env stores, 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.

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/pyproject.toml

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

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/src/agentenv_protocol/agent_env_environment.py

@@ -14,7 +14,8 @@ import sys
 import types
 import uuid
 from abc import ABC, abstractmethod
-from typing import Annotated, Any, Callable, ClassVar, Literal, NamedTuple, Union, get_args, get_origin, get_type_hints
+from typing import (Annotated, Any, Callable, ClassVar, Literal, NamedTuple, Optional, Union, get_args, get_origin,
+                    get_type_hints)
 
 from pydantic import TypeAdapter, ValidationError
 from pydantic.fields import FieldInfo
@@ -376,7 +377,10 @@ class AgentEnvApplication(ABC):
         return self.environment_card
 
     async def _serve_card(self, request: Request) -> Response:
-        return _json_response(self.environment_card.model_dump())
+        card = self.environment_card
+        if isinstance(self.handler, AgentEnvEnvironment) and (children := await self.handler.children_environments()):
+            card = card.model_copy(update={"children_environments": children})
+        return _json_response(card.model_dump())
 
     async def update_tool(self, name: str, *, description: str) -> None:
         """Change a served tool's description after the mount: on the card and in tools/list alike."""
@@ -662,6 +666,11 @@ class AgentEnvEnvironment:
         """Declaration-only extensions to advertise, like ``intake/v1``: a promise with params and no handler."""
         return []
 
+    async def children_environments(self) -> Optional[list[EnvironmentCard]]:
+        """The environments this one fronts, as each serves its card with its paths under this one's, listed on the card
+        each time it's served; None for none."""
+        return None
+
     def served_extensions(self, extensions: list[EnvironmentExtension]) -> list[EnvironmentExtension]:
         """The ``@extension`` handlers' extensions to serve, chosen at mount: one left out is not served, and of one served
         with ``op``, only the methods its returned descriptor still lists."""

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/src/agentenv_protocol/client.py

@@ -147,6 +147,12 @@ def intake_declaration(card: dict) -> dict | None:
     return params if params else None
 
 
+def operations(card: dict) -> list[str] | None:
+    """The data-plane methods a card declares it serves (``capabilities.operations``), or None when it declares none,
+    as an older card doesn't."""
+    return (card.get("capabilities") or {}).get("operations")
+
+
 def find_tool(card: dict, name: str) -> dict | None:
     """Return the MCP tool advertised under `name`, or None.
 

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/src/agentenv_protocol/computer/__init__.py

@@ -67,6 +67,7 @@ from .operations import (
     type_text,
     write_files,
 )
+from .dataplane import part_bytes
 from .keys import PRINTABLE_KEYS
 from .manifest import ManifestSegment, RecordingManifest
 from .platform import Platform
@@ -107,7 +108,7 @@ __all__ = [
     "ComputerAppEnvironment", "computer_app", "install", "linux", "install_step", "ready_check", "Linux", "Service",
     "Launch", "Ready", "Packages", "AptSource", "Download", "RunScript",
     "AppDeclaration", "AppOs",
-    "APP_SETTINGS_ENV",
+    "APP_SETTINGS_ENV", "part_bytes",
     "Display", "Image", "Effect", "ExecResult", "ReadyCheck", "Platform", "ComputerSettings", "SETTINGS_ENV",
     "PRINTABLE_KEYS",
     "display", "set_display", "capture", "click", "drag", "scroll", "type_text", "press",

{agentenv_framework_protocol-0.1.418 → agentenv_framework_protocol-0.1.420}/src/agentenv_protocol/computer/app.py

@@ -1,24 +1,32 @@
 """ComputerAppEnvironment: software on a computer, an AgentEnvEnvironment whose class also declares what it is for a
 computer: the platforms it supports and the permissions it needs (``@computer_app``); for each OS, how it installs and
 launches there and what differs there (``@linux``, or ``@install`` for any OS type); its install steps and ready checks,
-each on every OS or on those it names; its skill, its typed ``Settings`` and its ``BuildSettings``. A ``computer_app``
-env's put reads that declaration from the class; its data hooks are the base class's. Its name is its env's
-``environment_name``. On the computer the class runs as the app's own server (``serve_app``), which launches the app,
-adds its launcher and says whether it's ready (``computer-app/v1``), as declared for the OS it runs on."""
+each on every OS or on those it names; its skill, its typed ``Settings`` and its ``BuildSettings``; and its data, the
+``paths`` it keeps it in under the session user's home or its own ``@add_data``, ``@get_data`` and ``@reset_data``
+hooks. A ``computer_app`` env's put reads that declaration from the class. Its name is its env's ``environment_name``.
+On the computer the class runs as the app's own server (``serve_app``), which launches the app, adds its launcher, says
+whether it's ready (``computer-app/v1``), serves its skill, and serves its data plane, stopping the app around a load
+and a reset, as declared for the OS it runs on."""
 from __future__ import annotations
 
 import functools
 import inspect
+import itertools
 import json
 import os
 from dataclasses import dataclass
 from pathlib import Path, PurePosixPath
 from typing import Annotated, Any, Callable, ClassVar, Literal, Optional, Union
 
-from pydantic import AfterValidator, BaseModel, ConfigDict, Field, create_model, field_validator, model_validator
+from pydantic import (AfterValidator, BaseModel, ConfigDict, Field, TypeAdapter, ValidationError, create_model,
+                      field_validator, model_validator)
 
-from ..agent_env_environment import _EXT_ATTR, _OP_ATTR, AgentEnvEnvironment, extension
-from ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, SKILL_EXTENSION_URI
+from ..agent_env_environment import (_EXT_ATTR, _OP_ATTR, OP_ADD_DATA, OP_GET_DATA, OP_RESET_DATA, AgentEnvEnvironment,
+                                     add_data, agent_skill, extension, get_data, reset_data)
+from ..transfers import RelativePath, WriteNamespaceGrant
+from ..types import (METHOD_ADD, METHOD_GET, METHOD_RESET, SKILL_EXTENSION_URI, EnvironmentExtension, IntakeDeclaration,
+                     IntakeFormat, intake_extension)
+from .app_data import AppDataPlane
 from .app_runtime import AppRuntime
 from .errors import InvalidArgument
 from .platform import detect
@@ -27,7 +35,8 @@ from .platform import detect
 APP_SETTINGS_ENV = "AGENTENV_APP_SETTINGS"
 _INSTALL_STEP_ATTR = "_aee_install_step"
 _READY_CHECK_ATTR = "_aee_ready_check"
-_DATA_METHODS = {"reset_data": METHOD_RESET, "add_data": METHOD_ADD, "get_data": METHOD_GET}
+_DATA_METHODS = {OP_RESET_DATA: METHOD_RESET, OP_ADD_DATA: METHOD_ADD, OP_GET_DATA: METHOD_GET}
+_PATHS = TypeAdapter(list[RelativePath])
 #: What a launch's window can be matched by, as the session lists each window.
 WINDOW_KEYS = frozenset({"class", "instance", "title"})
 #: The framework extension an app's own server serves: its launch as params, and its ``launch`` and ``ready`` methods.
@@ -207,13 +216,15 @@ class AppReadyCheck(BaseModel):
 
 class AppOs(BaseModel):
     """What an app declares for one OS type: ``install``, how that OS installs it, as the OS type's install model gives
-    it; its ``launch`` there; and its ``skill``, ``settings`` and ``build_settings`` there when they differ from the
-    class's, the schemas with the class's fields added."""
+    it; its ``launch`` there; the ``paths`` it keeps its data in there, relative to the session user's home; and its
+    ``skill``, ``settings`` and ``build_settings`` there when they differ from the class's, the schemas with the class's
+    fields added."""
 
     model_config = ConfigDict(extra="forbid")
 
     install: dict[str, Any]
     launch: Optional[Launch] = None
+    paths: Optional[list[str]] = None
     skill: Optional[AppSkill] = None
     settings: Optional[dict[str, Any]] = None
     build_settings: Optional[dict[str, Any]] = None
@@ -258,6 +269,7 @@ class _OsDeclared:
 
     install: BaseModel
     launch: Optional[Launch]
+    paths: tuple[str, ...]
     skill: Optional[str]
     settings: Optional[type[BaseModel]]
     build_settings: Optional[type[BaseModel]]
@@ -274,17 +286,26 @@ def computer_app(*, supports: Optional[list] = None, permissions: Optional[list[
     return deco
 
 
-def install(os_type: str, spec: BaseModel, *, launch: Optional[Launch] = None, skill: Optional[str] = None,
-            settings: Optional[type[BaseModel]] = None,
+def install(os_type: str, spec: BaseModel, *, launch: Optional[Launch] = None, paths: Optional[list[str]] = None,
+            skill: Optional[str] = None, settings: Optional[type[BaseModel]] = None,
             build_settings: Optional[type[BaseModel]] = None) -> Callable:
     """Declare how a computer of ``os_type`` installs the app, ``spec`` being that OS type's install model, and what is
-    the app's own there: its ``launch``; its ``skill``, a file of its folder, instead of the class's; and ``settings``
-    and ``build_settings``, models whose fields add to the class's ``Settings`` and ``BuildSettings`` there. ``@linux``
-    is this for Linux; an OS type a plugin adds is declared with it."""
+    the app's own there: its ``launch``; the ``paths`` it keeps its data in, relative to the session user's home, which
+    serve its data plane when it has no data hooks; its ``skill``, a file of its folder, instead of the class's; and
+    ``settings`` and ``build_settings``, models whose fields add to the class's ``Settings`` and ``BuildSettings`` there.
+    ``@linux`` is this for Linux; an OS type a plugin adds is declared with it."""
+    try:
+        owned = tuple(_PATHS.validate_python(list(paths or [])))
+    except ValidationError:
+        raise ValueError(f"paths are normalized paths relative to the session user's home, not {paths!r}") from None
+    if overlapping := [f"{a!r} and {b!r}" for a, b in itertools.combinations(owned, 2)
+                       if PurePosixPath(a).is_relative_to(b) or PurePosixPath(b).is_relative_to(a)]:
+        raise ValueError(f"an app's paths each hold files of their own, but {'; '.join(overlapping)} overlap")
+
     def deco(cls: type) -> type:
         if not (isinstance(cls, type) and issubclass(cls, ComputerAppEnvironment)):
             raise TypeError("@install decorates a ComputerAppEnvironment subclass")
-        cls._installs = {**cls._installs, os_type: _OsDeclared(spec, launch, skill, settings, build_settings)}
+        cls._installs = {**cls._installs, os_type: _OsDeclared(spec, launch, owned, skill, settings, build_settings)}
         return cls
     return deco
 
@@ -292,12 +313,13 @@ def install(os_type: str, spec: BaseModel, *, launch: Optional[Launch] = None, s
 def linux(*, files: str = ".", packages: Optional[Packages] = None, python: Optional[str] = None,
           sources: Optional[list[AptSource]] = None, downloads: Optional[list[Download]] = None,
           run: Optional[list[RunScript]] = None, services: Optional[list[Service]] = None,
-          ports: Optional[list[int]] = None, launch: Optional[Launch] = None, skill: Optional[str] = None,
-          settings: Optional[type[BaseModel]] = None, build_settings: Optional[type[BaseModel]] = None) -> Callable:
+          ports: Optional[list[int]] = None, launch: Optional[Launch] = None, paths: Optional[list[str]] = None,
+          skill: Optional[str] = None, settings: Optional[type[BaseModel]] = None,
+          build_settings: Optional[type[BaseModel]] = None) -> Callable:
     """``@install`` for Linux: how a Linux computer installs the app, ``Linux``'s fields, and what is its own there."""
     return install("linux", Linux(files=files, packages=packages, python=python, sources=sources, downloads=downloads,
                                   run=run, services=services or [], ports=ports),
-                   launch=launch, skill=skill, settings=settings, build_settings=build_settings)
+                   launch=launch, paths=paths, skill=skill, settings=settings, build_settings=build_settings)
 
 
 def install_step(scope: Literal["system", "session"] = "system", *,
@@ -328,15 +350,41 @@ def _named(os_types: Union[str, list[str], None]) -> Optional[list[str]]:
 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
-    ``self.build_settings``, and its launch as ``self.launch``, each as declared for the OS it runs on."""
+    ``self.build_settings``, and its launch and paths as ``self.launch`` and ``self.paths``, each as declared for the OS
+    it runs on.
+
+    Its data plane is its ``@add_data``, ``@get_data`` and ``@reset_data`` hooks, or, with none, defaults on its
+    ``paths``, which the base class serves around its contract (``app_data.AppDataPlane``): one call at a time, a load
+    and a reset with the app stopped and relaunched after, a load that fails followed by a reset, and each call within
+    ``data_timeout_s``."""
 
     supports: ClassVar[list] = []
     permissions: ClassVar[list[str]] = []
     _installs: ClassVar[dict[str, _OsDeclared]] = {}
+    #: Its data hooks' method names, by the operation each serves.
+    _data_hooks: ClassVar[dict[str, str]] = {}
     _computer_app: Optional[AppRuntime] = None
+    _computer_app_data: Optional[AppDataPlane] = None
     launch: Optional[Launch] = None
+    paths: list[str] = []
     #: A file of the app's folder holding its skill for agents, when no ``@agent_skill`` method writes it.
     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
+
+    def __init_subclass__(cls, **kwargs: Any) -> None:
+        """Take the class's data hooks over, for the base class's handlers to serve around its contract; and serve its
+        skill file unless it writes its skill itself."""
+        super().__init_subclass__(**kwargs)
+        hooks = dict(cls._data_hooks)
+        for name, member in vars(cls).items():
+            if (op := getattr(member, _OP_ATTR, None)) in _DATA_METHODS:
+                hooks[op] = name
+                delattr(member, _OP_ATTR)
+        cls._data_hooks = hooks
+        if any(getattr(getattr(member, _EXT_ATTR, None), "uri", None) == SKILL_EXTENSION_URI
+               for member in vars(cls).values()):
+            cls._computer_app_skill = None
 
     class Settings(BaseModel):
         """The app's settings: an app declares its own; a ``SecretStr`` field is a secret."""
@@ -350,12 +398,17 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
         values = json.loads(os.environ.get(APP_SETTINGS_ENV) or "{}").get(os.environ.get("ENVIRONMENT_NAME"), {})
         self.settings = cls.settings_on(on).model_validate(values)
         self.build_settings = _built_settings(cls, on)
-        self.launch = declared.launch if (declared := cls._installs.get(on)) is not None else None
+        declared = cls._installs.get(on)
+        self.launch = declared.launch if declared is not None else None
+        self.paths = list(declared.paths) if declared is not None else []
         ready = self.launch.ready if self.launch is not None else None
         self._computer_app = AppRuntime(
             self.launch, {fn.__name__: getattr(self, fn.__name__) for fn in _methods(cls)
                           if hasattr(fn, _READY_CHECK_ATTR) and _runs_on(getattr(fn, _READY_CHECK_ATTR), on)},
             ready.timeout_s if ready is not None else DEFAULT_TIMEOUT_S)
+        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)
 
     @classmethod
     def settings_on(cls, os_type: Optional[str]) -> type[BaseModel]:
@@ -375,7 +428,7 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
     async def _computer_app_launch(self) -> dict:
         if self.launch is None:
             raise InvalidArgument(f"{type(self).__name__} declares no launch")
-        return {"pid": await self._computer_app_runtime().launch_app()}
+        return {"pid": await self._computer_app_data_plane().launch()}
 
     @extension(COMPUTER_APP, op="ready", method="GET")
     async def _computer_app_ready(self) -> dict:
@@ -386,11 +439,61 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
             raise TypeError(f"{type(self).__qualname__}.__init__ must call super().__init__()")
         return self._computer_app
 
+    def _computer_app_data_plane(self) -> AppDataPlane:
+        self._computer_app_runtime()
+        return self._computer_app_data
+
     def extension_params(self, uri: str) -> dict:
         if uri == COMPUTER_APP:
-            return {"launch": self.launch.model_dump(mode="json", exclude_none=True) if self.launch else None}
+            return {"launch": self.launch.model_dump(mode="json", exclude_none=True) if self.launch else None,
+                    "paths": self.paths}
         return super().extension_params(uri)
 
+    def served_operations(self, operations: list[str]) -> list[str]:
+        """Its hooks' operations, or with none, all three when it has paths."""
+        served = ({_DATA_METHODS[op] for op in self._data_hooks} if self._data_hooks
+                  else set(_DATA_METHODS.values()) if self.paths else set())
+        return [op for op in operations if op in served]
+
+    def served_extensions(self, extensions: list[EnvironmentExtension]) -> list[EnvironmentExtension]:
+        """Without its skill file on this OS, no skill, unless it writes one itself."""
+        own_skill = getattr(type(self), "_computer_app_skill", None) is not None
+        if own_skill and self._computer_app_skill_file() is None:
+            extensions = [extension for extension in extensions if extension.uri != SKILL_EXTENSION_URI]
+        return super().served_extensions(extensions)
+
+    def declared_extensions(self) -> list[EnvironmentExtension]:
+        """With its paths serving its data, a file tree: ``data/get`` returns a part per file."""
+        declared = super().declared_extensions()
+        if self.paths and not self._data_hooks:
+            tree = IntakeDeclaration(get=[IntakeFormat(part="file", format="file-tree")],
+                                     add=[IntakeFormat(part="file", format="file-tree", load="additive")])
+            declared.append(intake_extension(tree, f"data/add writes files under the app's paths, "
+                                                   f"{', '.join(self.paths)}; data/get returns them; data/reset puts "
+                                                   "them back as installed."))
+        return declared
+
+    @add_data
+    async def _computer_app_add_data(self, parts: list) -> None:
+        await self._computer_app_data_plane().call(OP_ADD_DATA, parts)
+
+    @get_data
+    async def _computer_app_get_data(self, write_namespace: Optional[WriteNamespaceGrant] = None) -> list:
+        return await self._computer_app_data_plane().call(OP_GET_DATA, write_namespace)
+
+    @reset_data
+    async def _computer_app_reset_data(self) -> None:
+        await self._computer_app_data_plane().call(OP_RESET_DATA)
+
+    @agent_skill
+    def _computer_app_skill(self) -> tuple[str, str]:
+        return _skill_parts(Path(self._computer_app_skill_file()).read_text(), os.environ.get("ENVIRONMENT_NAME", ""))
+
+    def _computer_app_skill_file(self) -> Optional[str]:
+        """The file of the app's folder holding its skill on this OS, or the class's."""
+        declared = type(self)._installs.get(detect().os)
+        return declared.skill if declared is not None and declared.skill is not None else type(self).skill
+
     @classmethod
     def declaration(cls) -> AppDeclaration:
         """What the class declares. Raises ValueError for a skill declared twice, a build setting that's a secret, or
@@ -404,7 +507,8 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
                                  "it in Settings")
         methods = _methods(cls)
         skill_methods = [fn.__name__ for fn in methods
-                         if getattr(getattr(fn, _EXT_ATTR, None), "uri", None) == SKILL_EXTENSION_URI]
+                         if getattr(getattr(fn, _EXT_ATTR, None), "uri", None) == SKILL_EXTENSION_URI
+                         and not fn.__name__.startswith("_computer_app_")]
         if cls.skill is not None and skill_methods:
             raise ValueError(f"{cls.__name__} declares its skill twice: skill = {cls.skill!r} and @agent_skill "
                              f"{skill_methods[0]}")
@@ -425,6 +529,7 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
             supports=cls.supports, permissions=cls.permissions,
             os={os_type: AppOs(
                 install=declared.install.model_dump(mode="json", exclude_none=True), launch=declared.launch,
+                paths=list(declared.paths) or None,
                 skill=AppSkill(file=declared.skill) if declared.skill is not None else None,
                 settings=cls.settings_on(os_type).model_json_schema() if declared.settings is not None else None,
                 build_settings=(cls.build_settings_on(os_type).model_json_schema()
@@ -433,11 +538,23 @@ class ComputerAppEnvironment(AgentEnvEnvironment):
             settings=cls.Settings.model_json_schema(), build_settings=build if build.get("properties") else None,
             skill=AppSkill(file=cls.skill) if cls.skill is not None else
                   AppSkill(method=skill_methods[0]) if skill_methods else None,
-            data=sorted({_DATA_METHODS[op] for fn in methods if (op := getattr(fn, _OP_ATTR, None)) in _DATA_METHODS}),
+            data=sorted(_DATA_METHODS[op] for op in cls._data_hooks),
             install_steps=steps, ready_checks=checks,
         )
 
 
+def _skill_parts(text: str, name: str) -> tuple[str, str]:
+    """A skill file's description and body: from its frontmatter's ``description`` when it has one."""
+    if text.startswith("---\n") and (end := text.find("\n---", 4)) != -1:
+        front, body = text[4:end], text[end + 4:].lstrip("\n")
+        description = next((line.partition(":")[2].strip().strip("'\"") for line in front.splitlines()
+                            if line.startswith("description:")), "")
+        if description:
+            return description, body
+        text = body
+    return f"How to use {name} on this computer.", text
+
+
 def _secret_at(schema: dict, path: str = "") -> Optional[str]:
     """Where in ``schema``, a JSON schema, a secret is, a ``SecretStr``'s ``writeOnly``: in it or any of its subschemas,
     a field's, a list's items or a nested model's definition; None when it holds none. A default or a field's name