rust

Rust SDK for the Agent Host Protocol

Transport-agnostic Rust client for AHP.

Crates

• ahp-types — Wire types generated from the TypeScript source of truth in types/. Regenerate with npm run generate:rust from the repo root.
• ahp — Async client, pure reducers, a pluggable Transport trait, and an ahp::hosts module for multi-host registry / reconnect / fan-in. No network dependencies — bring your own transport.
• ahp-ws — WebSocket transport adapter built on tokio-tungstenite.

Quick start

use ahp::{Client, ClientConfig, SubscriptionEvent};

let transport = ahp_ws::WebSocketTransport::connect("ws://localhost:12345").await?;
let client = Client::connect(transport, ClientConfig::default()).await?;

let init = client
    .initialize("my-client".into(), vec![ahp_types::PROTOCOL_VERSION.to_string()], vec![ahp_types::ROOT_RESOURCE_URI.to_string()])
    .await?;

let mut sub = client.attach_subscription(ahp_types::ROOT_RESOURCE_URI).await;
while let Some(SubscriptionEvent::Action(a)) = sub.recv().await {
    println!("seq={} {:?}", a.server_seq, a.action);
}

Using a custom transport

Implement ahp::Transport for any framed bytes stream — stdio, a Unix socket, an in-memory channel pair, a TCP connection with your own framing, etc. The trait surface is three async methods:

pub trait Transport: Send + 'static {
    fn send(&mut self, msg: TransportMessage)
        -> impl Future<Output = Result<(), TransportError>> + Send;
    fn recv(&mut self)
        -> impl Future<Output = Result<Option<TransportMessage>, TransportError>> + Send;
    fn close(&mut self)
        -> impl Future<Output = Result<(), TransportError>> + Send { async { Ok(()) } }
}

See crates/ahp/tests/client_roundtrip.rs for a working in-memory transport used by the integration test.

Protocol version mapping

This crate exposes two protocol-version constants:

• ahp_types::PROTOCOL_VERSION — the SemVer string for the version the crate's 0.x.y source tree implements.
• ahp_types::SUPPORTED_PROTOCOL_VERSIONS — every version this crate is willing to negotiate, most-preferred-first. Pass the slice (or a derived Vec<String>) as InitializeParams.protocol_versions.

The same information is mirrored, in machine-readable form, in clients/rust/release-metadata.json and, in human-readable form, in CHANGELOG.md.

Regenerating types

npm run generate:rust

The generator (scripts/generate-rust.ts) parses types/*.ts with ts-morph and emits Rust modules under crates/ahp-types/src/. Do not edit the generated files by hand.

Running tests

cargo test --workspace

Multi-host clients

See MULTI_HOST.md for the Rust SDK's multi-host registry, reconnect supervision, fan-in events, aggregated views, and single-host convenience API.