Struct AtdClient 

pub struct AtdClient { /* private fields */ }

Async ATD client.

Each request/response pair is serialized under an internal mutex so the client is safe to clone across tasks by wrapping in Arc<AtdClient>.

Implementations

impl AtdClient

pub async fn connect(endpoint: Endpoint) -> Result<Self, AtdError>

Connect with default retry behaviour (read from env, see ConnectOptions). For explicit control use AtdClient::connect_with_options.

pub async fn connect_with_options( endpoint: Endpoint, opts: ConnectOptions, ) -> Result<Self, AtdError>

SP-concurrency-baseline §5.3 — connect with explicit retry policy.

Retries on transient errors (refused / reset / would-block / timeout) with exponential backoff capped at opts.backoff_cap_ms and ±20% jitter to break lockstep retries during a spawn-storm. Short-circuits on truly fatal errors (NotFound, PermissionDenied) where retry cannot help. Each attempt is wrapped in tokio::time::timeout(opts.connect_timeout_ms) so a stalled connect() + ping() round-trip surfaces as a retryable error instead of hanging.

pub async fn ping(&self) -> Result<(), AtdError>

pub async fn hello( &self, client_id: Option<&str>, requested: Vec<String>, ) -> Result<Vec<String>, AtdError>

SP-12 Hello handshake. Declare the capabilities the client would like to hold on this connection; returns the subset the server actually granted.

Back-compat: pre-SP-12 servers do not recognize hello and will typically respond with a wire error. This method demotes that to “no capabilities granted” (Ok(vec![])) so callers can treat the pre-SP-12 case identically to the fail-closed SP-12 case — a single hello() call works against any server version.

pub async fn hello_with_ucan_tokens( &self, client_id: Option<&str>, requested: Vec<String>, ucan_tokens: Vec<String>, ) -> Result<Vec<String>, AtdError>

SP-capability-v2 extension of Self::hello.

Same handshake but also presents ucan_tokens — each entry a UCAN-lite JWT compact form. The server verifies each chain independently and replies with granted_capabilities = (server_allow_list ∩ requested) ∪ ucan_derived_caps.

On verifier failures the server returns a Response::Error with one of codes 1010 (ERR_UCAN_INVALID) / 1011 (ERR_UCAN_EXPIRED) / 1012 (ERR_DELEGATION_TOO_DEEP) / 1013 (ERR_AUDIENCE_MISMATCH); this method surfaces that as AtdError for the caller to inspect, without the “pre-SP-12 demote to empty” fallback hello() uses — UCAN failures are deterministic and the caller wants to know.

pub async fn discover( &self, query: Option<&str>, filter: DiscoverFilter, ) -> Result<Vec<ToolSummary>, AtdError>

pub async fn describe(&self, tool_id: &str) -> Result<ToolDefinition, AtdError>

pub async fn call_page( &self, tool_id: &str, args: Value, cursor: Option<&str>, opts: CallOptions, ) -> Result<PaginatedSdkResult, AtdError>

SP-pagination-v1 §4.8 — fetch one page of a paginated tool result.

On the initial call, pass cursor = None. The server’s response carries next_cursor; pass it verbatim to the next call_page to fetch the subsequent page. Cursors are opaque — clients MUST NOT parse them.

For tools that don’t paginate, the first page returns next_cursor: None and the response shape is identical to call.

pub async fn call_all( &self, tool_id: &str, args: Value, opts: CallAllOptions, ) -> Result<Value, AtdError>

SP-pagination-v1 §4.8 — fetch all pages via auto-loop, merging per the configured MergePolicy. Aborts with PaginationLimitExceeded if max_pages or max_total_bytes is hit before exhaustion.

pub async fn call( &self, tool_id: &str, args: Value, opts: CallOptions, ) -> Result<ToolResult, AtdError>