| name | agent-desktop-ffi |
| version | 0.4.1 |
| tags | ffi, c-bindings, cdylib, python, swift, node, go, rust-ffi |
| requirements | ["agent-desktop-ffi"] |
| description | C-ABI bindings over agent-desktop's PlatformAdapter. Consumers (Python ctypes, Swift, Node ffi-napi, Go cgo, C++, Ruby fiddle) link libagent_desktop_ffi.{dylib,so,dll} and call `ad_*` functions directly instead of spawning the CLI binary per call. The canonical observe-act workflow is: ad_init → ad_adapter_create[_with_session] → ad_snapshot → parse @e refs → ad_execute_by_ref → ad_free_string → ad_adapter_destroy.
|
agent-desktop-ffi
Direct C-ABI access to every PlatformAdapter operation. Build the
cdylib with the workspace's 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, .dll on Windows) plus a committed C header at
crates/ffi/include/agent_desktop.h.
A Python ctypes smoke harness lives at tests/ffi-python/smoke.py and
serves as a worked end-to-end example covering the ABI handshake, struct
size validation, ad_version, and the snapshot pipeline leg. See
tests/ffi-python/README.md for usage.
Four reference topics, loaded as needed:
- ownership.md — who allocates / who frees,
for every
*mut T the FFI hands back to the caller.
- error-handling.md — errno-style
last-error contract, enum validation, panic boundary.
- threading.md — host-thread contract,
cross-process mutation serialization, AXIsProcessTrusted inheritance,
and adapter-bound native handles.
- build-and-link.md — ABI handshake,
struct size validation, minimal C and Python examples, observe-act
workflow, and prebuilt archive locations.
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", NULL, &act, 0, &result_out)
ad_free_string(result_out)
ad_adapter_destroy(adapter)
ad_snapshot returns a {version, ok, command, data} JSON envelope
identical to the CLI output. The data.tree field contains snapshot-qualified
ref IDs for interactive elements. Pass a qualified ref, or a legacy bare ref
plus its explicit snapshot_id, to ad_execute_by_ref to drive the pipeline
(RefStore load → strict resolution → actionability preflight → dispatch).
Core constraints
-
ABI handshake. Call ad_init(AD_ABI_VERSION_MAJOR) once after loading the
dylib. A mismatch between the compiled-in constant and the loaded dylib returns
AD_RESULT_ERR_INVALID_ARGS — abort rather than proceed. You can also read the
raw dylib major via ad_abi_version() for diagnostic display. New ad_* symbols
and new error codes are additive (no bump required); removed or layout-changed
symbols increment the major.
-
Session adapters. ad_adapter_create_with_session("session-id") associates
the adapter with a session namespace for refmap persistence — the same as CLI
--session <id>. A null snapshot_id is valid only for a qualified ref;
legacy bare @eN refs require an explicit snapshot ID. Session IDs: 1–64
chars, ASCII alphanumeric / - / _.
Invalid IDs return null (check ad_last_error_*).
-
Structured session trace (no ABI change). File-based JSONL tracing activates
only when the session has a manifest with trace: on from session start
(CLI) or equivalent on-disk setup. ad_adapter_create_with_session alone does
not create trace files. When tracing is active, command_context()-backed
commands append to one segment per OS process under
~/.agent-desktop/sessions/<id>/trace/<pid>-<procTs>.jsonl. A long-lived host
reuses the same segment filename for all calls in that process. For unstructured
diagnostics regardless of session manifest, use ad_set_log_callback (below).
-
Threading and mutation leases. Adapter entrypoints may be called from any
host thread. Native handles remain bound to their creating adapter and thread.
Desktop mutations acquire the same canonical cross-process interaction lease
as the CLI; reads carry finite deadlines without taking the mutation lock. See
threading.md for the Apple documentation basis and
the read/read, read/mutation, and mutation/mutation ordering matrix.
-
Release profile. cargo build --release produces panic = "abort" —
any Rust panic inside an extern "C" fn will SIGABRT the host. Use
--profile release-ffi to get the correct profile. CI
enforces this.
