Struct AgentHandle 

pub struct AgentHandle { /* private fields */ }

A handle to an agent instance that manages its lifecycle.

AgentHandle wraps an AgentCore and provides:

• Socket path and PID file tracking
• Lifecycle management (shutdown, status checks)
• Thread-safe access to the underlying AgentCore
• Idle timeout and key locking

Unlike the previous global static pattern, multiple AgentHandle instances can coexist, enabling proper testing and multi-agent scenarios.

Implementations

impl AgentHandle

pub fn new(socket_path: PathBuf) -> Self

Creates a new agent handle with the specified socket path.

pub fn with_timeout(socket_path: PathBuf, idle_timeout: Duration) -> Self

Creates a new agent handle with the specified socket path and idle timeout, using the default absolute unlock cap.

pub fn with_unlock_cap( socket_path: PathBuf, idle_timeout: Duration, max_unlock_ttl: Duration, ) -> Self

Creates a new agent handle with an explicit idle timeout and absolute unlock cap.

The idle timeout locks the agent after a period of no signing (a “walked away” control); the unlock cap locks it a fixed time after it was last unlocked, regardless of activity, so continuous signing cannot keep it unlocked forever.

Args:

• socket_path: The Unix-domain socket path.
• idle_timeout: Sliding inactivity timeout (0 disables).
• max_unlock_ttl: Absolute cap measured from the last unlock (0 disables).

Usage:

let handle = AgentHandle::with_unlock_cap(path, idle, cap);

pub fn with_pid_file(socket_path: PathBuf, pid_file: PathBuf) -> Self

Creates a new agent handle with socket and PID file paths.

pub fn with_pid_file_and_timeout( socket_path: PathBuf, pid_file: PathBuf, idle_timeout: Duration, ) -> Self

Creates a new agent handle with socket, PID file, and custom timeout.

pub fn from_core(core: AgentCore, socket_path: PathBuf) -> Self

Creates an agent handle from an existing AgentCore.

pub fn socket_path(&self) -> &PathBuf

Returns the socket path for this agent.

pub fn pid_file(&self) -> Option<&PathBuf>

Returns the PID file path, if configured.

pub fn set_pid_file(&mut self, path: PathBuf)

Sets the PID file path.

pub fn lock(&self) -> Result<MutexGuard<'_, AgentCore>, AgentError>

Acquires a lock on the agent core.

Errors

Returns AgentError::MutexError if the mutex is poisoned.

pub fn core_arc(&self) -> Arc<Mutex<AgentCore>>

Returns a clone of the inner Arc<Mutex<AgentCore>> for sharing.

pub fn is_running(&self) -> bool

Returns whether the agent is currently running.

pub fn set_running(&self, running: bool)

Marks the agent as running.

pub fn idle_timeout(&self) -> Duration

Returns the configured idle timeout duration.

pub fn touch(&self)

Records activity, resetting the idle timer.

pub fn idle_duration(&self) -> Duration

Returns the duration since the last activity.

pub fn is_idle_timed_out(&self) -> bool

Returns whether the agent has exceeded the idle timeout.

pub fn max_unlock_ttl(&self) -> Duration

Returns the absolute cap on how long a single unlock keeps signing capability.

pub fn unlock_age(&self) -> Duration

Returns the time elapsed since the agent was last unlocked.

pub fn is_unlock_window_expired(&self) -> bool

Returns whether the agent has been unlocked longer than its absolute cap.

Unlike the idle timeout, this does not reset on activity — it bounds the total lifetime of a single unlock so continuous signing cannot keep the agent unlocked indefinitely. A cap of 0 disables it.

pub fn is_agent_locked(&self) -> bool

Returns whether the agent is currently locked.

pub fn lock_agent(&self) -> Result<(), AgentError>

Locks the agent, clearing all keys from memory.

After locking, sign operations will fail with AgentError::AgentLocked.

pub fn unlock_agent(&self)

Unlocks the agent (marks as unlocked).

Note: This only clears the locked flag. Keys must be re-loaded separately using register_key or the CLI auths agent unlock command.

pub fn check_idle_timeout(&self) -> Result<bool, AgentError>

Locks the agent if its unlock window has ended, clearing its keys.

The agent locks when it has been idle past the idle timeout (a “walked away” control) or when it has been unlocked longer than the absolute cap (a backstop so continuous signing cannot keep it unlocked indefinitely). Call this periodically from a background task. Neither control stops a process running as the same user from using the agent within the window — they only bound the window.

pub fn shutdown(&self) -> Result<(), AgentError>

Shuts down the agent, clearing all keys and resources.

This method:

1. Clears all keys from the agent core (zeroizing sensitive data)
2. Marks the agent as not running
3. Optionally removes the socket file and PID file

pub fn key_count(&self) -> Result<usize, AgentError>

Returns the number of keys currently loaded in the agent.

pub fn public_keys(&self) -> Result<Vec<Vec<u8>>, AgentError>

Returns all public key bytes currently registered.

pub fn register_key( &self, pkcs8_bytes: Zeroizing<Vec<u8>>, ) -> Result<(), AgentError>

Registers a key in the agent core.

pub fn sign(&self, pubkey: &[u8], data: &[u8]) -> Result<Vec<u8>, AgentError>

Signs data using a key in the agent core.

Errors

Returns AgentError::AgentLocked if the agent is locked.

Trait Implementations

impl Clone for AgentHandle

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for AgentHandle

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.