agentenv-framework-protocol 0.1.377__tar.gz → 0.1.379__tar.gz

{agentenv_framework_protocol-0.1.377 → agentenv_framework_protocol-0.1.379}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: agentenv-framework-protocol
-Version: 0.1.377
+Version: 0.1.379
 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
@@ -370,8 +370,8 @@ one as a `ComputerDriverEnvironment` subclass from `agentenv_protocol.computer`,
 `computer` extra (`pip install 'agentenv-framework-protocol[computer]'`: mcp, uvicorn and Pillow).
 The driver marks the methods that capture the screen and send input; the base class serves the
 computer contract from them, so the tools, results and errors can't drift from it. A complete
-driver for an X11 desktop, with an image to run it in, is in
-[`examples/computer_x11/`](https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/examples/computer_x11).
+driver for an X11 desktop is agent-env's reference driver, in its
+[`drivers` bundle](https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/drivers).
 
 ```python
 from agentenv_protocol.computer import (
@@ -473,6 +473,42 @@ and `exec_timeout_s`. A driver reads them as `self.settings`, for example its ta
 Every caller is `default` until agents carry an identity of their own; `caller_identity(context)`
 names the caller whose latest frame and others' input a call uses.
 
+`MyDriver.declaration(platform)` returns the card the class serves on a `Platform`, built without
+running the driver, its operations or its dependencies.
+
+### Checking a driver: the conformance probe
+
+The probe checks a running driver against the contract through its card, tools and extensions. It
+reports each check, and gives each extension the card declares a verdict: verified, unverified or
+failed.
+
+```bash
+python -m agentenv_protocol.computer.conformance http://localhost:18765 [--level basic|full] [--json report.json]
+```
+
+```python
+from agentenv_protocol.computer.conformance import run_probe
+
+report = await run_probe("http://localhost:18765", "full")   # a ProbeReport
+failed = [c for c in report.checks if c.status == "failed"]
+```
+
+The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver.
+
+| Level | Checks | Needs on the computer |
+|---|---|---|
+| `basic` | P0 ready and a screenshot; P1 the card and tool schemas; P2 native frames, regions and JPEG; P5 refusals and their codes; X the declared extensions (`computer-display`, `computer-spaces`, `computer-keyboard`, `computer-exec`, `data/get`, per-role tool access, the pointer) | nothing |
+| `full` | `basic`, then P3 colours land where the mapping says; P4 clicks show their effect; P5 refusals change nothing; P6 typed and pressed keys arrive; P7 scrolls and drags arrive; P9 commands and `data/add` run as one unprivileged user; X pointer and keyboard input, `data/add` | Linux, `python3` with Tk, a 1280x800 screen or larger, `computer-exec` and `data/add` |
+
+At `full` the probe writes the Fixture Desk, a Tk window (`conformance/fixture.py`), into
+`~/.agentenv-probe` with `data/add` and starts it with `computer-exec`. It aims at the boxes the
+window's widgets report, reads back what reached them, and then removes the fixture. When the
+fixture can't be staged, the `full` checks are unverified rather than failed. The probe leaves out
+the checks for an extension the card doesn't declare. P8 is not applicable to a driver without
+leasing, and unverified for one with it until the probe has lease checks. The probe calls as the
+default role; the tool-access check hides a tool from a role of its own, `agentenv-probe-<random>`,
+and gives it back.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:

{agentenv_framework_protocol-0.1.377 → agentenv_framework_protocol-0.1.379}/README.md

@@ -319,8 +319,8 @@ one as a `ComputerDriverEnvironment` subclass from `agentenv_protocol.computer`,
 `computer` extra (`pip install 'agentenv-framework-protocol[computer]'`: mcp, uvicorn and Pillow).
 The driver marks the methods that capture the screen and send input; the base class serves the
 computer contract from them, so the tools, results and errors can't drift from it. A complete
-driver for an X11 desktop, with an image to run it in, is in
-[`examples/computer_x11/`](https://github.com/scaleapi/agentenv-framework/tree/main/packages/agentenv-protocol/examples/computer_x11).
+driver for an X11 desktop is agent-env's reference driver, in its
+[`drivers` bundle](https://github.com/scaleapi/agentenv-framework/tree/main/src/agent_env/drivers).
 
 ```python
 from agentenv_protocol.computer import (
@@ -422,6 +422,42 @@ and `exec_timeout_s`. A driver reads them as `self.settings`, for example its ta
 Every caller is `default` until agents carry an identity of their own; `caller_identity(context)`
 names the caller whose latest frame and others' input a call uses.
 
+`MyDriver.declaration(platform)` returns the card the class serves on a `Platform`, built without
+running the driver, its operations or its dependencies.
+
+### Checking a driver: the conformance probe
+
+The probe checks a running driver against the contract through its card, tools and extensions. It
+reports each check, and gives each extension the card declares a verdict: verified, unverified or
+failed.
+
+```bash
+python -m agentenv_protocol.computer.conformance http://localhost:18765 [--level basic|full] [--json report.json]
+```
+
+```python
+from agentenv_protocol.computer.conformance import run_probe
+
+report = await run_probe("http://localhost:18765", "full")   # a ProbeReport
+failed = [c for c in report.checks if c.status == "failed"]
+```
+
+The CLI exits 0 when no check failed, 1 when one did and 2 when it can't reach the driver.
+
+| Level | Checks | Needs on the computer |
+|---|---|---|
+| `basic` | P0 ready and a screenshot; P1 the card and tool schemas; P2 native frames, regions and JPEG; P5 refusals and their codes; X the declared extensions (`computer-display`, `computer-spaces`, `computer-keyboard`, `computer-exec`, `data/get`, per-role tool access, the pointer) | nothing |
+| `full` | `basic`, then P3 colours land where the mapping says; P4 clicks show their effect; P5 refusals change nothing; P6 typed and pressed keys arrive; P7 scrolls and drags arrive; P9 commands and `data/add` run as one unprivileged user; X pointer and keyboard input, `data/add` | Linux, `python3` with Tk, a 1280x800 screen or larger, `computer-exec` and `data/add` |
+
+At `full` the probe writes the Fixture Desk, a Tk window (`conformance/fixture.py`), into
+`~/.agentenv-probe` with `data/add` and starts it with `computer-exec`. It aims at the boxes the
+window's widgets report, reads back what reached them, and then removes the fixture. When the
+fixture can't be staged, the `full` checks are unverified rather than failed. The probe leaves out
+the checks for an extension the card doesn't declare. P8 is not applicable to a driver without
+leasing, and unverified for one with it until the probe has lease checks. The probe calls as the
+default role; the tool-access check hides a tool from a role of its own, `agentenv-probe-<random>`,
+and gives it back.
+
 ## A2A agent framework
 
 The distribution exposes two unrelated decorators named `extension`:

{agentenv_framework_protocol-0.1.377 → agentenv_framework_protocol-0.1.379}/pyproject.toml

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

agentenv_framework_protocol-0.1.379/src/agentenv_protocol/computer/_declare.py

@@ -0,0 +1,98 @@
+"""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."""
+from __future__ import annotations
+
+import contextlib
+import importlib.abc
+import importlib.machinery
+import importlib.util
+import json
+import sys
+import types
+from pathlib import Path
+
+from .card import COMPUTER
+from .driver import ComputerDriverEnvironment
+from .platform import supported
+
+
+class _StubMeta(type):
+    def __getattr__(cls, name: str):
+        if name.startswith("__"):
+            raise AttributeError(name)
+        return cls
+
+    def __call__(cls, *args, **kwargs):
+        return cls
+
+    def __getitem__(cls, key):
+        return cls
+
+
+class _Stub(metaclass=_StubMeta):
+    """Whatever a stubbed module holds: itself again on any attribute, call or index, and a class to derive from."""
+
+
+class _StubModule(types.ModuleType):
+    __path__: list = []
+
+    def __getattr__(self, name: str):
+        if name.startswith("__"):
+            raise AttributeError(name)
+        return _Stub
+
+
+class _Stubs(importlib.abc.MetaPathFinder, importlib.abc.Loader):
+    """Last on ``sys.meta_path``: a module no other finder finds imports as a stub."""
+
+    def find_spec(self, fullname, path, target=None):
+        return importlib.machinery.ModuleSpec(fullname, self, is_package=True)
+
+    def create_module(self, spec):
+        return _StubModule(spec.name)
+
+    def exec_module(self, module) -> None:
+        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."""
+    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 not (isinstance(cls, type) and issubclass(cls, ComputerDriverEnvironment)):
+        raise ValueError(f"{file} has no ComputerDriverEnvironment 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(e.params 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."""
+    folder, file, name = argv
+    try:
+        with contextlib.redirect_stdout(sys.stderr):
+            declared = declare(Path(folder), file, name)
+    except Exception as e:
+        print(f"{type(e).__name__}: {e}", file=sys.stderr)
+        return 1
+    print(json.dumps(declared))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

agentenv_framework_protocol-0.1.379/src/agentenv_protocol/computer/conformance/__init__.py

@@ -0,0 +1,22 @@
+"""The conformance probe: checks a running computer driver against the contract through its card, tools and
+extensions, and reports each check and each declared extension. ``basic`` needs nothing on the computer; ``full``
+stages the Linux fixture with data/add and reads it back with computer-exec. Run it as
+``python -m agentenv_protocol.computer.conformance <driver url> [--level basic|full] [--json report.json]``."""
+from __future__ import annotations
+
+from .checks import Probe
+from .client import Driver
+from .report import CheckResult, Level, ProbeReport, Status, Verdict
+
+__all__ = ["run_probe", "ProbeReport", "CheckResult", "Level", "Status", "Verdict"]
+
+
+async def run_probe(url: str, level: Level = "full", *, timeout_s: float = 60, ready_timeout_s: float = 60) -> ProbeReport:
+    """Probe the driver serving its card at ``url``. ``ready_timeout_s`` is how long it may take to report ready."""
+    driver = await Driver.connect(url, timeout_s)
+    async with driver.session() as session:
+        probe = Probe(driver, session, ready_timeout_s)
+        await probe.basic()
+        if level == "full":
+            await probe.full()
+    return ProbeReport.of(level, driver.name, probe.results, driver.extensions)

agentenv_framework_protocol-0.1.379/src/agentenv_protocol/computer/conformance/__main__.py

@@ -0,0 +1,42 @@
+"""``python -m agentenv_protocol.computer.conformance <driver url>``: probe a running driver, print each check, and
+exit 1 when one failed or 2 when the driver couldn't be reached."""
+from __future__ import annotations
+
+import argparse
+import asyncio
+import sys
+from pathlib import Path
+
+from . import run_probe
+
+_MARK = {"passed": "PASS", "failed": "FAIL", "unverified": "----", "not_applicable": "n/a "}
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="python -m agentenv_protocol.computer.conformance",
+                                     description="Probe a running computer driver against the contract.")
+    parser.add_argument("url", help="where the driver serves its card, such as http://localhost:18765")
+    parser.add_argument("--level", choices=("basic", "full"), default="full")
+    parser.add_argument("--json", type=Path, help="also write the report to this file")
+    parser.add_argument("--timeout", type=float, default=60, help="seconds for each call, and to report ready")
+    args = parser.parse_args(argv)
+    try:
+        report = asyncio.run(run_probe(args.url, args.level, timeout_s=args.timeout, ready_timeout_s=args.timeout))
+    except Exception as e:
+        print(f"couldn't probe {args.url}: {type(e).__name__}: {e}", file=sys.stderr)
+        return 2
+    for result in report.checks:
+        detail = f": {result.detail}" if result.detail else ""
+        print(f"{_MARK[result.status]} {result.check} {result.name}{detail}")
+    counts = report.counts()
+    print(f"{report.driver}: {counts['passed']} passed, {counts['failed']} failed, {counts['unverified']} unverified, "
+          f"{counts['not_applicable']} not applicable at {report.level}")
+    for uri, verdict in report.extensions.items():
+        print(f"  {verdict:10} {uri}")
+    if args.json:
+        args.json.write_text(report.model_dump_json(indent=1))
+    return 0 if report.passed else 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())