Direct C-ABI access to every PlatformAdapter operation. Build the
cdylib with the workspace's release-ffi profile:
-
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 panic = "unwind" profile. CI
enforces this.
-
Last-error lifetime. Pointers returned by ad_last_error_* remain valid
across any number of subsequent successful FFI calls on the same thread.
Only the next failing call rotates them. Cache the pointer once, read it as
many times as you need.
-
ad_last_error_details. A fourth accessor, ad_last_error_details(),
returns a borrowed JSON string carrying structured details (e.g. the
actionability check report on ACTION_FAILED, candidate summaries on
AMBIGUOUS_TARGET). The details may contain element names, values, and window
titles from the user's screen — treat as sensitive diagnostics and avoid routing
to shared log surfaces.
-
Handle release. Every ad_resolve_element_exact / ad_find_exact result must be
released with ad_free_handle(adapter, &handle) on the same adapter that
produced it, before that adapter is destroyed. On macOS this balances the
internal CFRetain; on Windows/Linux the call is a no-op but safe to issue.
ad_free_handle zeroes handle.ptr so a follow-up call is a safe no-op.
-
Primary ref-action path. ad_execute_by_ref is the recommended entrypoint
for the observe-act loop: it loads the RefStore, looks up the ref in the refmap
(STALE_REF on miss), runs strict element re-identification (STALE_REF / AMBIGUOUS_TARGET),
runs the live actionability preflight, then dispatches. TypeText and PressKey
default to focus_fallback policy (matching CLI type/press-key); all other
actions default to headless. Pass AD_POLICY_KIND_HEADED (2) to opt in to
cursor-based fallbacks.
-
Generation-safe direct APIs. ABI-v3 legacy AdRefEntry and
AdWindowInfo layouts remain available for binary compatibility, but they do
not carry process-generation evidence and direct targeting functions fail
closed. Use AdExactRefEntry, AdExactWindowInfo,
ad_list_windows_exact, and the *_exact targeting symbols. Likewise,
ad_list_surfaces_exact preserves SurfaceInfo.id; the legacy surface list
is an observation-only projection that omits it.
-
Display discovery. Call ad_list_displays before using
AdScreenshotTarget.screen_index. List order is the screenshot index order;
inspect each AdDisplayInfo for its stable display ID, bounds, primary flag,
and scale, then release the handle with ad_display_list_free.
-
Low-level action paths. ad_execute_action (headless, no preflight) and
ad_execute_action_with_policy are raw escape hatches for callers holding a live
AdNativeHandle from ad_resolve_element_exact / ad_find_exact. Use them when
you need to bypass the ref-action pipeline.
-
Ref-action preflight. ad_execute_by_ref and
ad_execute_ref_action_exact_with_policy both resolve the element strictly and run the live actionability preflight
(visible, stable, enabled, supported action, policy, editable) before dispatching
— a disabled or unsupported target fails before any platform call. On
AD_RESULT_ERR_ACTION_FAILED, the structured check report is available as JSON
via ad_last_error_details().
-
Action result steps. AdActionResult.steps mirrors the CLI steps array
for activation-chain actions. Each entry has label and outcome strings and
is owned by the result; release with ad_free_action_result(&out).
-
Tracing / log callback. Two tracing surfaces coexist:
-
Structured file trace — same JSONL contract as CLI --trace, gated by a
trace: on session manifest. Segments include event, ts_ms, seq, and
redacted fields. Requires session start (or equivalent manifest on disk)
before creating the adapter; plain session-id adapters write nothing to disk.
-
ad_set_log_callback(cb) — installs a tracing subscriber layer that
delivers events as JSON to your callback. cb receives an int32_t level
(1=ERROR … 5=TRACE) and a const char *msg valid only for the duration of
the call. Pass NULL to unregister. The layer is installed on the first
non-null call; if a foreign global subscriber already owns the process at
that point, the install fails with AD_RESULT_ERR_INTERNAL and no events are
ever delivered. Sensitive field values (password, token, text, …) are
replaced with {"redacted":true} before formatting. A panicking callback is
caught and silently discarded. The callback may fire from threads other than
the registering thread, and may still fire briefly after a NULL unregister
— keep the callback and any data it captures valid for the process lifetime.
-
Wait. ad_wait(adapter, args, &out) runs the full CLI wait command
(element-appear, window-appear, text-appear, menu-open/close, notification,
element predicates). Zero-initialize AdWaitArgs, set the fields you need, and
validate the struct size against AD_WAIT_ARGS_SIZE / ad_wait_args_size() before
calling. The output is a {version, ok, command, data} JSON envelope freed with
ad_free_string. ad_wait blocks the calling thread up to timeout_ms ms —
ensure the adapter is not destroyed from another thread while it is running.
-
Text input privacy. On macOS, focus-fallback or headed text insertion may
briefly use the clipboard for non-ASCII text. For sensitive text, prefer
AD_ACTION_KIND_SET_VALUE with AD_POLICY_KIND_HEADLESS when the target
supports settable values.
-
Enum discriminants. Every #[repr(i32)] enum field is validated at the C
boundary — invalid discriminants return AD_RESULT_ERR_INVALID_ARGS instead of
undefined behavior.
-
ABI stability. The major version in AD_ABI_VERSION_MAJOR increments on any
breaking change (removed symbol, incompatible layout). Additive changes (new
symbols, new error codes) do not bump it. Before 1.0, pin the exact version of
libagent_desktop_ffi you link against.
-
ad_get_tree_exact vs ad_snapshot. ad_get_tree_exact returns a raw flat BFS tree
without @e refs, no refmap persistence, and no JSON envelope — use it for
custom traversal or UI inspection. For observe-act agents that drive actions via
ad_execute_by_ref, always start with ad_snapshot.
