agent-desktop-ffi

agent-desktop-ffi

Direct C-ABI access to the same operations as the CLI. Build the cdylib with the release-ffi profile:

cargo build --profile release-ffi -p agent-desktop-ffi

The output is target/release-ffi/libagent_desktop_ffi.dylib (.so on Linux, agent_desktop_ffi.dll on Windows) plus a committed C header at crates/ffi/include/agent_desktop.h. The default release profile uses panic = "abort": a Rust panic inside an extern "C" function would SIGABRT the host. release-ffi keeps panic = "unwind", which the panic traps need.

Four reference topics, loaded as needed:

• ownership.md: who allocates and who frees every pointer the FFI hands back.
• error-handling.md: errno-style last-error contract, error codes, enum validation, panic boundary.
• threading.md: host-thread contract, mutation ordering across threads and processes, adapter-bound native handles, AXIsProcessTrusted inheritance.
• build-and-link.md: prebuilt archives, ABI handshake, struct size validation, C and Python examples.

Observe-act workflow (canonical path)

ad_init(AD_ABI_VERSION_MAJOR)                    // verify header ↔ dylib match
adapter = ad_adapter_create_with_session("s1")   // or ad_adapter_create()
rc = ad_snapshot(adapter, "Finder", 0, 10, false, false, &json_out)
// parse json_out: locate snapshot-qualified refs in data.tree
ad_free_string(json_out)
// build action:
AdAction act = {0}; act.kind = AD_ACTION_KIND_CLICK;
rc = ad_execute_by_ref(adapter, "@s8f3k2p9:e5", &act, 0, &result_out)
ad_free_string(result_out)
ad_adapter_destroy(adapter)

ad_snapshot returns the CLI envelope {version, ok, command, data}. data.tree carries snapshot-qualified refs for interactive elements. Read data.complete before trusting a tree: false means the observation budget ran out and the tree is partial, not an error. ad_snapshot reads the owner selected by surface. On macOS, menu and menubar are application-owned, need no document window, and omit data.window; window-owned snapshots include it. Window targeting, skeleton mode and --root drill-down are not exposed over the ABI. A bare @eN ref returns AD_RESULT_ERR_INVALID_ARGS.