use-computer-cli 0.1.0__tar.gz → 0.1.1__tar.gz

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: use-computer-cli
-Version: 0.1.0
+Version: 0.1.1
 Summary: Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot.
 Project-URL: Homepage, https://github.com/applica-software-guru/use-computer
 Author: Bruno Fortunato
@@ -83,7 +83,7 @@ project. The command it installs is `use-computer`, and the package it imports i
 use-computer click --x 120 --y 340 --use staging
 use-computer type --text "hello" --use staging
 use-computer key ctrl+s --use staging
-use-computer screenshot --use laptop --out shot.png
+use-computer screenshot --use laptop            # writes a file, returns its path
 
 # a batch runs over one connection -- the default command, so `batch` may be omitted
 echo '[{"action":"click","x":120,"y":340},{"action":"key","combo":"enter"}]' \
@@ -93,6 +93,9 @@ echo '[{"action":"click","x":120,"y":340},{"action":"key","combo":"enter"}]' \
 stdout is one JSON object per run; every diagnostic goes to stderr. Exit codes: `0` success,
 `1` failure, `2` bad usage.
 
+Screenshots are files, never bytes in the JSON. `--verify` writes the screen it captured after the
+action and reports the path, so a verified action does not need a `screenshot` call after it.
+
 ## Three problems it solves
 
 - **Coordinate spaces.** A screenshot on a HiDPI display is larger than the space the OS clicks

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/README.md

@@ -27,7 +27,7 @@ project. The command it installs is `use-computer`, and the package it imports i
 use-computer click --x 120 --y 340 --use staging
 use-computer type --text "hello" --use staging
 use-computer key ctrl+s --use staging
-use-computer screenshot --use laptop --out shot.png
+use-computer screenshot --use laptop            # writes a file, returns its path
 
 # a batch runs over one connection -- the default command, so `batch` may be omitted
 echo '[{"action":"click","x":120,"y":340},{"action":"key","combo":"enter"}]' \
@@ -37,6 +37,9 @@ echo '[{"action":"click","x":120,"y":340},{"action":"key","combo":"enter"}]' \
 stdout is one JSON object per run; every diagnostic goes to stderr. Exit codes: `0` success,
 `1` failure, `2` bad usage.
 
+Screenshots are files, never bytes in the JSON. `--verify` writes the screen it captured after the
+action and reports the path, so a verified action does not need a `screenshot` call after it.
+
 ## Three problems it solves
 
 - **Coordinate spaces.** A screenshot on a HiDPI display is larger than the space the OS clicks

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "use-computer-cli"
-version = "0.1.0"
+version = "0.1.1"
 description = "Execute input on a screen for computer-use agents: move, click, drag, scroll, type, key, screenshot."
 readme = "README.md"
 requires-python = ">=3.10"

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/actions.py

@@ -138,8 +138,9 @@ class KeyAction(BaseAction):
 
 class ScreenshotAction(BaseAction):
     action: Literal["screenshot"] = "screenshot"
-    out: Path | None = None
-    base64: bool = False
+    out: Path | None = Field(
+        default=None, description="Where to write it. None means the screenshot directory."
+    )
 
 
 Action = Annotated[

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/cli.py

@@ -323,14 +323,16 @@ def key(
 
 @app.command()
 def screenshot(
-    out: Annotated[Path | None, typer.Option("--out", help="Write the PNG here.")] = None,
-    base64: Annotated[bool, typer.Option("--base64", help="Include the PNG in the JSON.")] = False,
+    out: Annotated[
+        Path | None,
+        typer.Option("--out", help="Write the PNG here. Otherwise the screenshot directory."),
+    ] = None,
     use: UseOption = None,
     verbose: VerboseOption = 0,
 ) -> None:
-    """Capture the current screen."""
+    """Capture the current screen to a file and report its path."""
     config = _config(use, verbose=verbose)
-    _run([ScreenshotAction(out=out, base64=base64)], config, verbose)
+    _run([ScreenshotAction(out=out)], config, verbose)
 
 
 @app.command()

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/compare.py

@@ -10,7 +10,6 @@ downscaled greyscale images. This module is pure: it takes images and returns a
 
 from __future__ import annotations
 
-import base64
 import io
 from datetime import datetime, timezone
 from pathlib import Path
@@ -31,12 +30,17 @@ PIXEL_DELTA = 16
 
 
 class Screenshot(BaseModel):
-    """A captured screen."""
+    """A captured screen.
+
+    ``data`` is held only while a comparison needs it. It is excluded from serialisation: a
+    screenshot that reaches the calling agent is a path, never a megabyte of base64 in its
+    context.
+    """
 
     model_config = ConfigDict(frozen=True)
 
     path: Path | None = None
-    data: bytes | None = Field(default=None, repr=False)
+    data: bytes | None = Field(default=None, repr=False, exclude=True)
     width: int
     height: int
     space: CoordinateSpace = CoordinateSpace.SCREENSHOT
@@ -50,13 +54,18 @@ class Screenshot(BaseModel):
             return Image.open(self.path)
         raise ValueError("screenshot has neither data nor path")
 
-    def base64(self) -> str:
-        """The PNG bytes, base64-encoded, for transport to the calling agent."""
+    def write_to(self, path: Path) -> Screenshot:
+        """Write the PNG to ``path`` and return the screenshot that knows where it lives."""
+        if self.path == path:
+            return self
+        path.parent.mkdir(parents=True, exist_ok=True)
         if self.data is not None:
-            return base64.b64encode(self.data).decode("ascii")
-        if self.path is not None:
-            return base64.b64encode(self.path.read_bytes()).decode("ascii")
-        raise ValueError("screenshot has neither data nor path")
+            path.write_bytes(self.data)
+        elif self.path is not None:
+            path.write_bytes(self.path.read_bytes())
+        else:
+            raise ValueError("screenshot has neither data nor path")
+        return self.model_copy(update={"path": path})
 
 
 class ChangeReport(BaseModel):

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/config.py

@@ -72,6 +72,10 @@ class Settings(BaseSettings):
     verify: bool = False
     verify_threshold: float = DEFAULT_THRESHOLD
     space: CoordinateSpace = CoordinateSpace.SCREENSHOT
+    screenshot_dir: Path | None = Field(
+        default=None,
+        description="Where screenshots go when no path was given. None means the XDG data dir.",
+    )
     dry_run: bool = False
     allow_local: bool = False
     continue_on_error: bool = False
@@ -197,6 +201,15 @@ def xdg_data_dir() -> Path:
     return (Path(base) if base else Path.home() / ".local" / "share") / "use-computer"
 
 
+def default_screenshot_dir() -> Path:
+    """Where screenshots land when nothing said otherwise.
+
+    The XDG *data* directory: a screenshot of somebody's desktop is not disposable like a cache,
+    and it does not belong in a working tree.
+    """
+    return xdg_data_dir() / "screenshots"
+
+
 def env_var_for(field: str) -> str:
     return ENV_PREFIX + field.upper()
 
@@ -505,6 +518,7 @@ def write_initial_config(
 _TRUE = {"1", "true", "yes", "on"}
 _FALSE = {"0", "false", "no", "off"}
 _BOOL_FIELDS = frozenset({"verify", "dry_run", "allow_local", "continue_on_error"})
+_PATH_FIELDS = frozenset({"screenshot_dir"})
 _FLOAT_FIELDS = frozenset({"delay", "typing_rate", "verify_threshold", "scale"})
 
 
@@ -524,6 +538,8 @@ def _coerce(field: str, value: Any) -> Any:
             return float(value)
         except ValueError as exc:
             raise ConfigError(f"{env_var_for(field)}={value!r} is not a number") from exc
+    if field in _PATH_FIELDS:
+        return Path(value).expanduser()
     if field == "port":
         try:
             return int(value)

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/runner.py

@@ -9,6 +9,8 @@ from __future__ import annotations
 
 import time
 from collections.abc import Sequence
+from datetime import datetime, timezone
+from pathlib import Path
 from types import TracebackType
 from typing import Any
 
@@ -30,7 +32,12 @@ from use_computer.actions import (
 )
 from use_computer.backends import Backend, create_backend
 from use_computer.compare import ChangeReport, Screenshot, compare
-from use_computer.config import BackendProfile, ResolvedConfig, Settings
+from use_computer.config import (
+    BackendProfile,
+    ResolvedConfig,
+    Settings,
+    default_screenshot_dir,
+)
 from use_computer.config import load as load_config
 from use_computer.coordinates import Coordinate, ScreenInfo
 from use_computer.errors import UseComputerError
@@ -98,6 +105,7 @@ class Session:
         self._backend = backend
         self._profile = profile
         self._settings = settings or Settings()
+        self._screenshot_dir = self._settings.screenshot_dir or default_screenshot_dir()
         self._screen = backend.screen_info()
 
     @classmethod
@@ -199,8 +207,15 @@ class Session:
                 after = self._safe_screenshot()
                 if before is not None and after is not None:
                     change = compare(before, after, settings.verify_threshold)
-                is_capture = isinstance(action, ScreenshotAction)
-                screenshot = (screenshot or after) if is_capture else after
+                if isinstance(action, ScreenshotAction):
+                    # The action already captured and wrote one; do not write it twice.
+                    pass
+                elif after is not None:
+                    # The capture is paid for either way. Writing it down is what saves the
+                    # calling agent a round trip for a screen it already has.
+                    screenshot = after.write_to(
+                        self._screenshot_path(action.action)
+                    )
         except UseComputerError as exc:
             error = ErrorInfo.of(exc)
         except Exception as exc:  # a backend can fail in its own vocabulary
@@ -248,14 +263,12 @@ class Session:
 
     def _capture(self, action: ScreenshotAction) -> Screenshot:
         shot = self._backend.screenshot()
-        if action.out is not None:
-            action.out.parent.mkdir(parents=True, exist_ok=True)
-            if shot.data is not None:
-                action.out.write_bytes(shot.data)
-            shot = shot.model_copy(update={"path": action.out})
-        if not action.base64:
-            shot = shot.model_copy(update={"data": None if action.out else shot.data})
-        return shot
+        return shot.write_to(action.out or self._screenshot_path("screenshot"))
+
+    def _screenshot_path(self, label: str) -> Path:
+        """A name that sorts and does not collide."""
+        stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%f")[:-3] + "Z"
+        return self._screenshot_dir / f"{stamp}-{label}.png"
 
     def _safe_screenshot(self) -> Screenshot | None:
         """Change detection is advisory; a capture that fails must not fail the action."""
@@ -280,25 +293,6 @@ def run_actions(
 
 
 def as_json(result: RunResult) -> dict[str, Any]:
-    """The run payload, with screenshot bytes rendered as base64 where they were requested."""
-    payload = result.model_dump(mode="json", exclude={"results": {"__all__": {"screenshot"}}})
-    payload["results"] = [
-        {**item, "screenshot": _screenshot_json(action.screenshot)}
-        for item, action in zip(payload["results"], result.results, strict=True)
-    ]
-    return payload
-
-
-def _screenshot_json(shot: Screenshot | None) -> dict[str, Any] | None:
-    if shot is None:
-        return None
-    payload: dict[str, Any] = {
-        "path": str(shot.path) if shot.path else None,
-        "width": shot.width,
-        "height": shot.height,
-        "space": shot.space.value,
-        "captured_at": shot.captured_at.isoformat(),
-    }
-    if shot.data is not None:
-        payload["base64"] = shot.base64()
+    """The run payload. A screenshot is a path here, never bytes."""
+    payload: dict[str, Any] = result.model_dump(mode="json")
     return payload

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/src/use_computer/skill/SKILL.md

@@ -40,7 +40,7 @@ use-computer drag --from-x 10 --from-y 20 --to-x 300 --to-y 400 --use staging
 use-computer scroll --amount 3 --direction down --use staging
 use-computer type --text "hello world" --use staging
 use-computer key ctrl+s --use staging
-use-computer screenshot --out shot.png --use staging
+use-computer screenshot --use staging              # writes a file, returns its path
 ```
 
 `type` sends literal text. `ctrl+a` given to `type` types seven characters — use `key` for
@@ -70,7 +70,20 @@ echo '[
 batch stops at the first failure and reports `failed_index`, so you can resume from a known
 point. `--continue-on-error` runs the rest anyway.
 
-## Verify — how you know it worked
+## Screenshots are files
+
+A screenshot is never returned to you as bytes. It is written to a file and you get the path:
+
+```json
+"screenshot": {"path": "/home/you/.local/share/use-computer/screenshots/20260904T103012.481Z-click.png",
+               "width": 2560, "height": 1600, "space": "screenshot"}
+```
+
+Read the file when you actually need to look at the screen. Do not ask for the pixels by default —
+a batch of verified clicks would otherwise bury your context in base64, which is why that option
+does not exist.
+
+## Verify — how you know it worked, and what the screen looks like now
 
 A click that lands on nothing looks exactly like a click that worked. With `--verify` (or
 `"verify": true` on one action) each action reports:
@@ -79,6 +92,10 @@ A click that lands on nothing looks exactly like a click that worked. With `--ve
 "change": {"changed": true, "magnitude": 0.18, "threshold": 0.002, "bbox": [40,120,600,400]}
 ```
 
+**`--verify` also gives you the screenshot taken after the action**, at the `screenshot` path in
+the same result. It captured that screen to do the comparison, so you already paid for it: do not
+follow a verified action with a `screenshot` call. That is the round trip verify exists to save.
+
 - `changed: false` after a click → the coordinate was probably stale. **Ask ui-locator again.
   Do not click the same pixel twice.**
 - `changed: true` with a tiny `magnitude` in a corner → a clock or a caret, not a response.

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/tests/conftest.py

@@ -44,6 +44,10 @@ def isolated_env(monkeypatch: pytest.MonkeyPatch, tmp_path: Path) -> Iterator[No
     (home / ".local" / "share").mkdir(parents=True, exist_ok=True)
     monkeypatch.setenv("XDG_CONFIG_HOME", str(home / ".config"))
     monkeypatch.setenv("XDG_DATA_HOME", str(home / ".local" / "share"))
+    # Both mechanisms, because they are genuinely different: Path.home() consults HOME through
+    # os.path.expanduser, but a patched Path.home does not reach expanduser() at all -- and a
+    # path like "~/shots" resolves through the latter.
+    monkeypatch.setenv("HOME", str(home))
     monkeypatch.setattr(Path, "home", classmethod(lambda cls: home))
     yield
 
@@ -60,6 +64,23 @@ def project(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> Path:
     return root
 
 
+class CliResult(Protocol):
+    """What a CliRunner result gives us.
+
+    typer.testing re-exports click's Result without declaring it, so importing the name fails
+    under mypy strict on the supported typer floor -- and importing it from click directly would
+    mean depending on somebody else's transitive dependency. Structural typing needs neither.
+    """
+
+    exit_code: int
+
+    @property
+    def stdout(self) -> str: ...
+
+    @property
+    def stderr(self) -> str: ...
+
+
 class WriteConfig(Protocol):
     """Writes a config.toml into the project fixture's root."""
 

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/tests/test_cli.py

@@ -8,7 +8,7 @@ from importlib import metadata
 from pathlib import Path
 
 import pytest
-from typer.testing import CliRunner, Result
+from typer.testing import CliRunner
 
 if sys.version_info >= (3, 11):
     import tomllib
@@ -16,7 +16,7 @@ else:
     import tomli as tomllib
 
 import use_computer
-from tests.conftest import WriteConfig, strip_ansi
+from tests.conftest import CliResult, WriteConfig, strip_ansi
 from tests.fake_backend import FakeBackend
 from use_computer import cli
 from use_computer.cli import EXIT_FAILURE, EXIT_OK, EXIT_USAGE, app, apply_default_command
@@ -43,7 +43,7 @@ def runner() -> CliRunner:
     return CliRunner()
 
 
-def invoke(runner: CliRunner, *args: str) -> Result:
+def invoke(runner: CliRunner, *args: str) -> CliResult:
     return runner.invoke(app, list(args), catch_exceptions=False)
 
 

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/tests/test_config.py

@@ -7,7 +7,13 @@ from pathlib import Path
 import pytest
 
 from tests.conftest import WriteConfig
-from use_computer.config import PROJECT_DIR, find_project_root, load, xdg_config_dir
+from use_computer.config import (
+    PROJECT_DIR,
+    default_screenshot_dir,
+    find_project_root,
+    load,
+    xdg_config_dir,
+)
 from use_computer.errors import ConfigError
 
 CONFIG = """
@@ -165,3 +171,29 @@ def test_a_profile_field_default_is_reported_like_any_other(write_config: WriteC
         "env": "USE_COMPUTER_PORT",
         "source": payload["config-file"],
     }
+
+
+def test_the_screenshot_directory_defaults_to_the_xdg_data_dir(
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    # Never a cache directory: a screenshot of somebody's desktop is not disposable.
+    monkeypatch.setenv("XDG_DATA_HOME", "/somewhere/data")
+    assert default_screenshot_dir() == Path("/somewhere/data/use-computer/screenshots")
+
+
+def test_the_screenshot_directory_is_configurable_like_anything_else(
+    write_config: WriteConfig,
+) -> None:
+    # Prepended, not appended: a key after a [table] header belongs to that table.
+    write_config('screenshot-dir = "/shots"\n' + CONFIG)
+    resolved = load(profile="laptop", environ={})
+    assert resolved.settings.screenshot_dir == Path("/shots")
+    assert resolved.values["screenshot_dir"].layer == "config"
+
+
+def test_a_screenshot_directory_from_the_environment_is_a_path_not_a_string(
+    write_config: WriteConfig,
+) -> None:
+    write_config(CONFIG)
+    resolved = load(profile="laptop", environ={"USE_COMPUTER_SCREENSHOT_DIR": "~/shots"})
+    assert resolved.settings.screenshot_dir == Path.home() / "shots"

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/tests/test_config_init.py

@@ -7,9 +7,9 @@ import sys
 from pathlib import Path
 
 import pytest
-from typer.testing import CliRunner, Result
+from typer.testing import CliRunner
 
-from tests.conftest import strip_ansi
+from tests.conftest import CliResult, strip_ansi
 from tests.fake_backend import FakeBackend
 from use_computer.cli import EXIT_FAILURE, EXIT_OK, EXIT_USAGE, app
 from use_computer.config import (
@@ -24,7 +24,7 @@ from use_computer.config import (
 from use_computer.errors import ConfigError
 
 
-def invoke(*args: str, stdin_is_a_tty: bool = False) -> Result:
+def invoke(*args: str, stdin_is_a_tty: bool = False) -> CliResult:
     return CliRunner().invoke(app, list(args), catch_exceptions=False)
 
 

{use_computer_cli-0.1.0 → use_computer_cli-0.1.1}/tests/test_runner.py

@@ -148,14 +148,29 @@ def test_verification_is_off_unless_asked_for() -> None:
     assert result.results[0].change is None
 
 
-def test_a_screenshot_action_returns_the_capture() -> None:
+def test_a_screenshot_action_returns_a_path_and_never_bytes(tmp_path: Path) -> None:
     backend = FakeBackend()
-    result = session(backend).run([ScreenshotAction(base64=True)])
+    result = session(backend, screenshot_dir=tmp_path / 'shots').run([ScreenshotAction()])
     payload = as_json(result)
     shot = payload["results"][0]["screenshot"]
     assert shot is not None
     assert shot["width"] == 2560
-    assert shot["base64"]
+    assert Path(shot["path"]).is_file()
+    # A megabyte of base64 in the agent's context is the most expensive place it could go.
+    assert "base64" not in shot
+    assert "data" not in shot
+
+
+def test_a_screenshot_without_a_path_still_lands_in_the_screenshot_directory(
+    tmp_path: Path,
+) -> None:
+    backend = FakeBackend()
+    result = session(backend, screenshot_dir=tmp_path / 'shots').run([ScreenshotAction()])
+    written = list((tmp_path / 'shots').iterdir())
+    assert len(written) == 1
+    assert written[0].name.endswith("-screenshot.png")
+    assert result.results[0].screenshot is not None
+    assert result.results[0].screenshot.path == written[0]
 
 
 def test_a_screenshot_action_writes_the_file_it_was_given(tmp_path: Path) -> None:
@@ -164,6 +179,32 @@ def test_a_screenshot_action_writes_the_file_it_was_given(tmp_path: Path) -> Non
     result = session(backend).run([ScreenshotAction(out=out)])
     assert out.is_file()
     assert result.results[0].screenshot is not None
+    assert result.results[0].screenshot.path == out
+
+
+def test_verify_writes_the_screen_it_already_captured_and_reports_where(
+    tmp_path: Path,
+) -> None:
+    """The capture is paid for either way; the path is what saves the agent a round trip."""
+    backend = FakeBackend(colours=[(0, 0, 0), (255, 255, 255)])
+    result = session(backend, verify=True, screenshot_dir=tmp_path / 'shots').run(
+        [ClickAction(x=10, y=10)]
+    )
+    shot = result.results[0].screenshot
+    assert shot is not None
+    assert shot.path is not None
+    assert shot.path.is_file()
+    assert shot.path.name.endswith("-click.png")
+    assert result.results[0].change is not None
+
+
+def test_a_verified_batch_writes_one_file_per_action_not_two(tmp_path: Path) -> None:
+    # The after-screenshot of one action is reused as the before of the next.
+    backend = FakeBackend()
+    session(backend, verify=True, screenshot_dir=tmp_path / 'shots').run(
+        [ClickAction(x=1, y=1), ClickAction(x=2, y=2), ClickAction(x=3, y=3)]
+    )
+    assert len(list((tmp_path / 'shots').iterdir())) == 3
 
 
 def test_the_backend_is_closed_even_when_an_action_failed() -> None: