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 timeout.

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> 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 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>

Checks idle timeout and locks the agent if exceeded.

Call this periodically from a background task.

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.