agent-desktop/tests/ffi-python

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.