mirror of
https://github.com/lahfir/agent-desktop.git
synced 2026-07-26 17:12:15 +00:00
9023f331b3
Completes the FFI plan: U9 adds a Python ctypes smoke harness proving the C ABI from a non-Rust host; U10 adds cross-platform parity CI gates for header drift, codegen drift, panic-unwind, and stub-adapter passthrough; U11 generates the command-backed wrappers from build.rs templates with a committed drift-gated output. The C ABI stays byte-identical and the surface is Windows and Linux ready with no new FFI code.
68 lines
2.6 KiB
Markdown
68 lines
2.6 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```bash
|
|
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.
|