agentenv-framework-protocol 0.1.395__tar.gz → 0.1.397__tar.gz

{agentenv_framework_protocol-0.1.395 → agentenv_framework_protocol-0.1.397}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.395
+Version: 0.1.397
 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
@@ -590,6 +590,49 @@ leasing, and unverified for one with it until the probe has lease checks. The pr
 default role; the tool-access check hides a tool from a role of its own, `agentenv-probe-<random>`,
 and gives it back.
 
+## Computer apps
+
+A computer app is software an agent uses on a computer, beside the driver: a desktop app, a service
+or both. Write one as a `ComputerAppEnvironment` subclass from `agentenv_protocol.computer`, an
+`AgentEnvEnvironment` whose class also says what it is to a computer. It needs only the plain
+package: `agentenv_protocol.computer` imports what a driver needs (mcp, uvicorn, Pillow, PyAV) only
+when a driver's names are used.
+
+```python
+from pydantic import BaseModel, SecretStr
+from agentenv_protocol.computer import ComputerAppEnvironment, Launch, Linux, Service, computer_app
+
+@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}])
+class MailApp(ComputerAppEnvironment):
+    linux = Linux(python="requirements.txt", services=[Service(name="imap", command="venv/bin/python imap.py")])
+    launch = Launch(command=["thunderbird"], window={"class": "thunderbird"})
+    skill = "skill.md"
+
+    class Settings(BaseModel):
+        signature: str = ""
+        password: SecretStr = SecretStr("")
+```
+
+- **`@computer_app`** names the platforms the app supports, as a driver names them, and the
+  `permissions` it needs of the computer. Its env.toml names the rest: the app itself
+  (`environment_name`) and the `computer` and `driver` it deploys alone on.
+- **`linux = Linux(...)`** is how a Linux computer installs it: `files`, a folder of the app's
+  copied under its prefix; `python`, a requirements file there installed into a venv beside them;
+  `services`, programs the computer's init runs from the prefix as the session user.
+- **`launch = Launch(...)`** says how it starts in the desktop session, with it (`at="boot"`) or when
+  the agent opens it (`"demand"`), and `ready=Ready(...)` when it's ready; `@ready_check` marks a
+  method for readiness that needs logic, and `@install_step(scope=...)` one a computer runs as it
+  installs the app.
+- **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`.
+- **`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.
+
+`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.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:

{agentenv_framework_protocol-0.1.395 → agentenv_framework_protocol-0.1.397}/README.md

@@ -537,6 +537,49 @@ leasing, and unverified for one with it until the probe has lease checks. The pr
 default role; the tool-access check hides a tool from a role of its own, `agentenv-probe-<random>`,
 and gives it back.
 
+## Computer apps
+
+A computer app is software an agent uses on a computer, beside the driver: a desktop app, a service
+or both. Write one as a `ComputerAppEnvironment` subclass from `agentenv_protocol.computer`, an
+`AgentEnvEnvironment` whose class also says what it is to a computer. It needs only the plain
+package: `agentenv_protocol.computer` imports what a driver needs (mcp, uvicorn, Pillow, PyAV) only
+when a driver's names are used.
+
+```python
+from pydantic import BaseModel, SecretStr
+from agentenv_protocol.computer import ComputerAppEnvironment, Launch, Linux, Service, computer_app
+
+@computer_app(supports=[{"os": {"type": "linux", "display": ["x11"]}, "arch": ["amd64", "arm64"]}])
+class MailApp(ComputerAppEnvironment):
+    linux = Linux(python="requirements.txt", services=[Service(name="imap", command="venv/bin/python imap.py")])
+    launch = Launch(command=["thunderbird"], window={"class": "thunderbird"})
+    skill = "skill.md"
+
+    class Settings(BaseModel):
+        signature: str = ""
+        password: SecretStr = SecretStr("")
+```
+
+- **`@computer_app`** names the platforms the app supports, as a driver names them, and the
+  `permissions` it needs of the computer. Its env.toml names the rest: the app itself
+  (`environment_name`) and the `computer` and `driver` it deploys alone on.
+- **`linux = Linux(...)`** is how a Linux computer installs it: `files`, a folder of the app's
+  copied under its prefix; `python`, a requirements file there installed into a venv beside them;
+  `services`, programs the computer's init runs from the prefix as the session user.
+- **`launch = Launch(...)`** says how it starts in the desktop session, with it (`at="boot"`) or when
+  the agent opens it (`"demand"`), and `ready=Ready(...)` when it's ready; `@ready_check` marks a
+  method for readiness that needs logic, and `@install_step(scope=...)` one a computer runs as it
+  installs the app.
+- **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`.
+- **`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.
+
+`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.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:

{agentenv_framework_protocol-0.1.395 → agentenv_framework_protocol-0.1.397}/pyproject.toml

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

agentenv_framework_protocol-0.1.397/src/agentenv_protocol/computer/__init__.py

@@ -0,0 +1,112 @@
+"""The computer SDK. A driver subclasses ComputerDriverEnvironment, marks the methods that capture and send input, and
+serve()s it, which needs the ``computer`` extra: ``pip install 'agentenv-framework-protocol[computer]'``. An app
+subclasses ComputerAppEnvironment, which needs only the plain package, so what a driver needs is imported on first
+use."""
+
+from __future__ import annotations
+
+import importlib
+from typing import TYPE_CHECKING, Any
+
+from .app import (
+    APP_SETTINGS_ENV,
+    AppDeclaration,
+    ComputerAppEnvironment,
+    Launch,
+    Linux,
+    Ready,
+    Service,
+    computer_app,
+    install_step,
+    ready_check,
+)
+from .errors import (
+    BackgroundUnavailable,
+    ComputerError,
+    DeliveryFailed,
+    DeviceUnavailable,
+    InputBusy,
+    Internal,
+    InvalidArgument,
+    LimitExceeded,
+    OutOfBounds,
+    PermissionDenied,
+    StaleFrame,
+    TargetUnavailable,
+    Timeout,
+    Unsupported,
+)
+from .operations import (
+    Display,
+    Effect,
+    ExecResult,
+    Image,
+    ReadyCheck,
+    capture,
+    click,
+    display,
+    drag,
+    key_down,
+    key_up,
+    pointer_down,
+    pointer_move,
+    pointer_position,
+    pointer_up,
+    press,
+    record,
+    run_in_session,
+    scroll,
+    set_display,
+    type_text,
+    write_files,
+)
+from .manifest import ManifestSegment, RecordingManifest
+from .platform import Platform
+from .settings import SETTINGS_ENV, ComputerSettings
+
+if TYPE_CHECKING:
+    from .card import (
+        COMPUTER,
+        COMPUTER_DISPLAY,
+        COMPUTER_EXEC,
+        COMPUTER_KEYBOARD,
+        COMPUTER_POINTER,
+        COMPUTER_READY,
+        COMPUTER_RECORDING,
+        COMPUTER_SPACES,
+    )
+    from .driver import DEFAULT_IDENTITY, ComputerDriverEnvironment, DriverDeclaration, computer_driver
+    from .recording import RecordedFrame, RecordedSegment, RecordHints, Recording, frames_in_thread
+
+# The names whose modules need the computer extra (mcp, av and Pillow), by module.
+_ON_USE = {
+    "driver": ("ComputerDriverEnvironment", "computer_driver", "DEFAULT_IDENTITY", "DriverDeclaration"),
+    "card": ("COMPUTER", "COMPUTER_READY", "COMPUTER_DISPLAY", "COMPUTER_SPACES", "COMPUTER_POINTER",
+             "COMPUTER_KEYBOARD", "COMPUTER_EXEC", "COMPUTER_RECORDING"),
+    "recording": ("Recording", "RecordHints", "RecordedFrame", "RecordedSegment", "frames_in_thread"),
+}
+
+
+def __getattr__(name: str) -> Any:
+    module = next((module for module, names in _ON_USE.items() if name in names), None)
+    if module is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    return getattr(importlib.import_module(f"{__name__}.{module}"), name)
+
+
+__all__ = [
+    "ComputerDriverEnvironment", "computer_driver", "DEFAULT_IDENTITY", "DriverDeclaration",
+    "ComputerAppEnvironment", "computer_app", "install_step", "ready_check", "Linux", "Service", "Launch", "Ready",
+    "AppDeclaration",
+    "APP_SETTINGS_ENV",
+    "Display", "Image", "Effect", "ExecResult", "ReadyCheck", "Platform", "ComputerSettings", "SETTINGS_ENV",
+    "display", "set_display", "capture", "click", "drag", "scroll", "type_text", "press",
+    "pointer_move", "pointer_down", "pointer_up", "pointer_position", "key_down", "key_up",
+    "run_in_session", "write_files", "record", "Recording", "RecordHints", "RecordedFrame", "RecordedSegment",
+    "frames_in_thread", "RecordingManifest", "ManifestSegment",
+    "ComputerError", "InvalidArgument", "OutOfBounds", "StaleFrame", "InputBusy", "PermissionDenied", "Unsupported",
+    "BackgroundUnavailable", "TargetUnavailable", "DeviceUnavailable", "LimitExceeded", "Timeout", "DeliveryFailed",
+    "Internal",
+    "COMPUTER", "COMPUTER_READY", "COMPUTER_DISPLAY", "COMPUTER_SPACES", "COMPUTER_POINTER", "COMPUTER_KEYBOARD",
+    "COMPUTER_EXEC", "COMPUTER_RECORDING",
+]

{agentenv_framework_protocol-0.1.395 → agentenv_framework_protocol-0.1.397}/src/agentenv_protocol/computer/_declare.py

@@ -1,8 +1,8 @@
-"""Read a computer driver class where its own dependencies may not be installed, as a ``computer_driver`` env's put
-does: ``python -m agentenv_protocol.computer._declare <folder> <file> <class>`` imports the file with every module
-not installed here standing in as an inert stub, and prints what the class declares for each platform it supports as
-JSON. Nothing runs beyond defining the module and its classes, and a class that can't be defined even so exits 1
-with why."""
+"""Read a computer driver or app class where its own dependencies may not be installed, as a ``computer_driver`` or
+``computer_app`` env's put does: ``python -m agentenv_protocol.computer._declare <folder> <file> <class>`` imports the
+file with every module not installed here standing in as an inert stub, and prints what the class declares as JSON,
+as its base class says. Nothing runs beyond defining the module and its classes, and a class that can't be defined
+even so exits 1 with why."""
 from __future__ import annotations
 
 import contextlib
@@ -14,10 +14,14 @@ import sys
 import types
 from pathlib import Path
 
+from .app import AppDeclaration, ComputerAppEnvironment
 from .card import COMPUTER
-from .driver import ComputerDriverEnvironment
+from .driver import ComputerDriverEnvironment, DriverDeclaration, DriverPlatform
 from .platform import supported
 
+#: The env type that stores each kind of declaration, which the printed JSON carries as ``type``.
+_ENV_TYPES = {AppDeclaration: "computer_app", DriverDeclaration: "computer_driver"}
+
 
 class _StubMeta(type):
     def __getattr__(cls, name: str):
@@ -58,32 +62,35 @@ class _Stubs(importlib.abc.MetaPathFinder, importlib.abc.Loader):
         return None
 
 
-def declare(folder: Path, file: str, name: str) -> dict:
-    """What the class ``name`` in ``folder/file`` declares: its card's name, its ``supports``, and for each platform
-    those name, the extensions it provides, its tools and the computer/v1 features. Raises ValueError for a class
-    that isn't a driver or declares no platform."""
+def declare(folder: Path, file: str, name: str) -> AppDeclaration | DriverDeclaration:
+    """What the class ``name`` in ``folder/file`` declares: an app's ``ComputerAppEnvironment.declaration()``; a
+    driver's card name, its ``supports``, and for each platform those name, the extensions it provides, its tools and
+    the computer/v1 features. Raises ValueError for a class that is neither, or a driver that declares no platform."""
     sys.path.insert(0, str(folder))
     sys.meta_path.append(_Stubs())
     spec = importlib.util.spec_from_file_location("computer_driver_module", folder / file)
     module = importlib.util.module_from_spec(spec)
     spec.loader.exec_module(module)
     cls = getattr(module, name, None)
+    if isinstance(cls, type) and issubclass(cls, ComputerAppEnvironment):
+        return cls.declaration()
     if not (isinstance(cls, type) and issubclass(cls, ComputerDriverEnvironment)):
-        raise ValueError(f"{file} has no ComputerDriverEnvironment subclass named {name}")
+        raise ValueError(f"{file} has no ComputerDriverEnvironment or ComputerAppEnvironment subclass named {name}")
     platforms = [platform for entry in cls.supports for platform in supported(entry)]
     if not platforms:
         raise ValueError(f"{name} declares no platform: name them with @computer_driver(supports=[...])")
     cards = [(platform, cls.declaration(platform)) for platform in platforms]
-    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({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]}
+    return DriverDeclaration(name=cards[0][1].name, supports=list(cls.supports), platforms=[
+        DriverPlatform(platform=platform, provides=[e.uri for e in card.capabilities.extensions],
+                       tools=[t.name for t in card.capabilities.tools],
+                       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])
 
 
 def main(argv: list[str]) -> int:
-    """Print the declaration as the only output; what the module prints while it loads goes to stderr."""
+    """Print the declaration as the only output, its env type as ``type``; what the module prints while it loads goes
+    to stderr."""
     folder, file, name = argv
     try:
         with contextlib.redirect_stdout(sys.stderr):
@@ -91,7 +98,7 @@ def main(argv: list[str]) -> int:
     except Exception as e:
         print(f"{type(e).__name__}: {e}", file=sys.stderr)
         return 1
-    print(json.dumps(declared))
+    print(json.dumps({"type": _ENV_TYPES[type(declared)], **declared.model_dump(mode="json", exclude_none=True)}))
     return 0
 
 

agentenv_framework_protocol-0.1.397/src/agentenv_protocol/computer/app.py

@@ -0,0 +1,178 @@
+"""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``), how each OS installs it
+(``linux = Linux(...)``), how it launches (``launch``), its install steps and ready checks, its skill, and its typed
+``Settings``. 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``."""
+from __future__ import annotations
+
+import inspect
+import json
+import os
+from typing import Any, Callable, ClassVar, Literal, Optional
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from ..agent_env_environment import _EXT_ATTR, _OP_ATTR, AgentEnvEnvironment
+from ..types import METHOD_ADD, METHOD_GET, METHOD_RESET, SKILL_EXTENSION_URI
+
+#: The environment variable a computer delivers its apps' settings in: JSON of each app's values by its name.
+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}
+
+
+class Service(BaseModel):
+    """A program the computer's init runs from the app's folder as the session user; a relative program names one
+    there."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    command: str
+
+
+class Linux(BaseModel):
+    """How a Linux computer installs the app: ``files``, a folder of the app's copied under its prefix; ``python``, a
+    requirements file in that folder installed into a venv beside them; ``services``, programs its init runs."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    files: str = "."
+    python: Optional[str] = None
+    services: list[Service] = Field(default_factory=list)
+
+
+class Ready(BaseModel):
+    """When the app is ready: its window shown, a port answering or a command exiting 0, within ``timeout_s``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    window: bool = False
+    port: Optional[int] = None
+    command: Optional[list[str]] = None
+    timeout_s: float = 60
+
+
+class Launch(BaseModel):
+    """How the app starts in the desktop session: with it (``boot``) or when the agent opens it (``demand``)."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    at: Literal["boot", "demand"] = "boot"
+    command: list[str]
+    window: Optional[dict[str, str]] = None
+    ready: Optional[Ready] = None
+
+
+class AppSkill(BaseModel):
+    """Where an app's skill for agents comes from: a ``file`` of its folder, or the ``@agent_skill`` ``method`` that
+    writes it."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    file: Optional[str] = None
+    method: Optional[str] = None
+
+
+class InstallStep(BaseModel):
+    """An ``@install_step`` method, by name, and whom it runs as."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    scope: Literal["system", "session"]
+
+
+class AppDeclaration(BaseModel):
+    """What a ComputerAppEnvironment class declares, as a ``computer_app`` env stores it: the platforms it ``supports``,
+    as a driver names them; its ``install`` by OS type; ``settings``, the JSON schema of its ``Settings``; and the
+    ``data`` methods, ``install_steps`` and ``ready_checks`` it serves, by name."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    supports: list[dict[str, Any]]
+    permissions: list[str]
+    install: dict[str, Linux]
+    launch: Optional[Launch] = None
+    settings: dict[str, Any]
+    skill: Optional[AppSkill] = None
+    data: list[str]
+    install_steps: list[InstallStep]
+    ready_checks: list[str]
+
+
+def computer_app(*, supports: Optional[list] = None, permissions: Optional[list[str]] = None) -> Callable:
+    """Declare what an app is: the platforms it supports, as a driver names them, and the permissions it needs of the
+    computer. Its env.toml names it and the computer and driver it deploys alone on."""
+    def deco(cls: type) -> type:
+        if not (isinstance(cls, type) and issubclass(cls, ComputerAppEnvironment)):
+            raise TypeError("@computer_app decorates a ComputerAppEnvironment subclass")
+        cls.supports, cls.permissions = list(supports or []), list(permissions or [])
+        return cls
+    return deco
+
+
+def install_step(scope: Literal["system", "session"] = "system") -> Callable:
+    """Mark a method a computer runs as it installs the app, after its files, in the order the class defines them: as
+    root, or for ``session``, as the session user."""
+    def deco(fn: Callable) -> Callable:
+        setattr(fn, _INSTALL_STEP_ATTR, scope)
+        return fn
+    return deco
+
+
+def ready_check(fn: Callable) -> Callable:
+    """Mark a method that says whether the app is ready, when ``launch``'s ``ready`` can't."""
+    setattr(fn, _READY_CHECK_ATTR, True)
+    return fn
+
+
+class ComputerAppEnvironment(AgentEnvEnvironment):
+    """Subclass it, declare it with ``@computer_app``, and set ``linux``, ``launch`` and ``skill`` as class attributes;
+    a deploy's settings arrive as ``self.settings``."""
+
+    supports: ClassVar[list] = []
+    permissions: ClassVar[list[str]] = []
+    linux: ClassVar[Optional[Linux]] = None
+    launch: ClassVar[Optional[Launch]] = None
+    #: A file of the app's folder holding its skill for agents, when no ``@agent_skill`` method writes it.
+    skill: ClassVar[Optional[str]] = None
+
+    class Settings(BaseModel):
+        """The app's settings: an app declares its own; a ``SecretStr`` field is a secret."""
+
+    def __init__(self) -> None:
+        values = json.loads(os.environ.get(APP_SETTINGS_ENV) or "{}").get(os.environ.get("ENVIRONMENT_NAME"), {})
+        self.settings = self.Settings.model_validate(values)
+
+    @classmethod
+    def declaration(cls) -> AppDeclaration:
+        """What the class declares. Raises ValueError for a skill declared twice or an install that isn't a
+        ``Linux``."""
+        if cls.linux is not None and not isinstance(cls.linux, Linux):
+            raise ValueError(f"{cls.__name__}.linux is a Linux(...), not {cls.linux!r}")
+        methods = _methods(cls)
+        skill_methods = [fn.__name__ for fn in methods
+                         if getattr(getattr(fn, _EXT_ATTR, None), "uri", None) == SKILL_EXTENSION_URI]
+        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]}")
+        return AppDeclaration(
+            supports=cls.supports, permissions=cls.permissions,
+            install={"linux": cls.linux} if cls.linux is not None else {},
+            launch=cls.launch, settings=cls.Settings.model_json_schema(),
+            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}),
+            install_steps=[InstallStep(name=fn.__name__, scope=getattr(fn, _INSTALL_STEP_ATTR)) for fn in methods
+                           if hasattr(fn, _INSTALL_STEP_ATTR)],
+            ready_checks=[fn.__name__ for fn in methods if hasattr(fn, _READY_CHECK_ATTR)],
+        )
+
+
+def _methods(cls: type) -> list[Callable]:
+    """The class's methods, each as the class resolves its name, in the order they were first defined."""
+    names = dict.fromkeys(name for klass in reversed(cls.__mro__) for name, member in vars(klass).items()
+                          if inspect.isfunction(member))
+    return [method for name in names if inspect.isfunction(method := getattr(cls, name))]

{agentenv_framework_protocol-0.1.395 → agentenv_framework_protocol-0.1.397}/src/agentenv_protocol/computer/driver.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 import asyncio
 from typing import Any, Callable, ClassVar
 
+from pydantic import BaseModel, ConfigDict
+
 from ..agent_env_environment import _CARD_CONFIG_ATTR, AgentEnvEnvironment, AgentEnvFastMCPApplication, environment_card
 from ..tool_context import ToolContext
 from ..types import EnvironmentCard, EnvironmentExtension, EnvironmentTool
@@ -23,6 +25,29 @@ from .tools import Tools
 DEFAULT_IDENTITY = "default"
 
 
+class DriverPlatform(BaseModel):
+    """What a driver serves on one platform its ``supports`` names: the extensions it ``provides``, its ``tools`` and
+    its computer/v1 ``features``."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    platform: Platform
+    provides: list[str]
+    tools: list[str]
+    features: dict[str, Any]
+
+
+class DriverDeclaration(BaseModel):
+    """What a ComputerDriverEnvironment class declares, as a ``computer_driver`` env stores it: its card's ``name``, the
+    platforms it ``supports``, as predicates, and what it serves on each of them."""
+
+    model_config = ConfigDict(extra="forbid")
+
+    name: str
+    supports: list[dict[str, Any]]
+    platforms: list[DriverPlatform]
+
+
 class ComputerDriverEnvironment(Tools, Extensions, DataPlane, AgentEnvEnvironment):
     """Subclass it and mark the methods that capture and send input (see ``operations``); the class is checked when
     it is defined. Features are class attributes, on the card. A subclass's ``__init__`` calls ``super().__init__()``.