3f322728b4
Settle the Playwright-grade reliability contract in agent-desktop-core before the Windows/Linux adapters are built, so they inherit it instead of redesigning it. Every command now observes, waits, verifies, and reports honestly instead of firing blindly. Highlights: capability-supertrait split of PlatformAdapter with not_supported() defaults; canonical role/state vocabulary with live `is --property visible`; display enumeration (`list-displays`) and honest `--screen` with scale factor; truthful Automation permission; `native_id` identity spine; window-id-first resolution; serializable `LocatorQuery` with live `find`; default-on auto-wait before every ref action; three-way `hit_test` occlusion gate; `scroll_into_view` in core; core accessible-name precedence; typed `ActionStep` delivery tier; `ProcessState` and `APP_UNRESPONSIVE`; `LaunchOptions`; baseline-diff desktop signals (`wait --event`); typed clipboard (`Text`/`Image`/`FileUrls`); mouse modifier chords and `mouse-wheel`. Hardened through a 35-reviewer pass with independent validation and a green live e2e gate (109/0), plus a head-vs-main performance comparison harness. BREAKING CHANGE: default-on auto-wait changes the timing of every previously-untouched ref-action call (bounded 5000 ms default; `--timeout-ms 0` restores single-shot). `ENVELOPE_VERSION` is now `2.1` (adds the `APP_UNRESPONSIVE` code and process state in error details). FFI ABI major is `3` (append-only struct evolution; `wait --event` is intentionally not exposed over FFI). The legacy string clipboard API is removed in favor of typed content. `key-down`/`key-up` fail closed until daemon-owned held input exists. `close-app` verifies termination and the osascript fallback path is removed. `--text` matching is subtree containment: `find --text X --first` returns the outermost matching container. |
||
|---|---|---|
| .. | ||
| README.md | ||
| smoke.py | ||
FFI Python Smoke Harness
Proves the C ABI works from a non-Rust host (Python ctypes) and gates it in CI.
What it tests
| Leg | Check |
|---|---|
| 1 | ad_abi_version() equals AD_ABI_VERSION_MAJOR from the header (catches header/dylib mismatch at import) |
| 2 | Every ad_*_size() getter equals the corresponding AD_*_SIZE macro (catches struct layout drift) |
| 3 | ad_version() returns ok:true JSON with data.version (basic command pipeline) |
| 4 | ad_adapter_create → ad_snapshot → ad_free_string → ad_adapter_destroy without crash or leak; stub adapter yields a clean PLATFORM_NOT_SUPPORTED envelope |
Building the dylib
# From the repo root:
cargo build --locked --profile release-ffi -p agent-desktop-ffi --features stub-adapter
The dylib lands at target/release-ffi/libagent_desktop_ffi.dylib (macOS) or
target/release-ffi/libagent_desktop_ffi.so (Linux).
--profile release-ffi keeps panic = "unwind", which is required for the
catch_unwind traps inside the FFI layer. Using the default release profile
(which has panic = "abort") would silently defeat those traps.
--features stub-adapter replaces the real platform adapter with a no-op that
returns PLATFORM_NOT_SUPPORTED for every adapter call. This lets CI run the
harness without requiring macOS Accessibility permissions.
Running locally
# macOS (arm64 or x86_64):
python3 tests/ffi-python/smoke.py \
target/release-ffi/libagent_desktop_ffi.dylib \
crates/ffi/include/agent_desktop.h
Alternatively, use environment variables:
export AD_DYLIB_PATH=target/release-ffi/libagent_desktop_ffi.dylib
export AD_HEADER_PATH=crates/ffi/include/agent_desktop.h
python3 tests/ffi-python/smoke.py
Stub enforcement (AD_EXPECT_STUB=1)
Set AD_EXPECT_STUB=1 when running the harness against a stub-adapter build.
With this variable set, the harness fails if ad_snapshot() returns ok:true,
which would indicate the dylib was not built with --features stub-adapter.
CI always sets this variable so a real-adapter dylib cannot accidentally pass the
stub-only gate.
Dependencies
smoke.py uses only the Python standard library (ctypes, json, re,
pathlib, sys). No pip install required.
Real-adapter happy path
The smoke harness gates the AX-independent surface (ABI version, struct sizes,
ad_version) and the PLATFORM_NOT_SUPPORTED passthrough path. The real-adapter
happy path (a successful ad_snapshot with ok:true) is covered by the E2E
harness (tests/e2e/run.sh), which requires AX permission and a release build
without the stub feature.