Address Rust SDK review comments

Author: willwashburn

packages/sdk-rust/src/lib.rs

@@ -64,6 +64,53 @@
 //!     Ok(())
 //! }
 //! ```
+//!
+//! ## Raw Events and Normalization
+//!
+//! ```rust,no_run
+//! use relaycast::{normalize_inbound_event, WsClient, WsClientOptions};
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let mut ws = WsClient::new(WsClientOptions::new("at_live_agent_token"));
+//!     let mut raw_events = ws.subscribe_raw_events();
+//!     ws.connect().await?;
+//!
+//!     while let Ok(raw) = raw_events.recv().await {
+//!         if let Some(event) = normalize_inbound_event(&raw) {
+//!             println!("{} -> {}: {}", event.from, event.target, event.text);
+//!         }
+//!     }
+//!
+//!     Ok(())
+//! }
+//! ```
+//!
+//! ## Registration and Channel Startup
+//!
+//! ```rust,no_run
+//! use relaycast::{
+//!     AgentRegistrationClient, CreateChannelRequest, RelayCast, RelayCastOptions,
+//! };
+//!
+//! #[tokio::main]
+//! async fn main() -> Result<(), Box<dyn std::error::Error>> {
+//!     let relay = RelayCast::new(RelayCastOptions::new("rk_live_your_api_key"))?;
+//!     let registration = AgentRegistrationClient::new(relay, "codex");
+//!     let agent = registration
+//!         .registered_agent_client("worker-a", Some("codex"))
+//!         .await?;
+//!
+//!     agent.ensure_joined_channel(CreateChannelRequest {
+//!         name: "general".to_string(),
+//!         topic: Some("General discussion".to_string()),
+//!         metadata: None,
+//!     }).await?;
+//!     agent.send("#general", "ready", None, None, None).await?;
+//!
+//!     Ok(())
+//! }
+//! ```
 
 pub mod agent;
 pub mod client;

packages/sdk-rust/src/ws.rs

@@ -344,14 +344,14 @@ impl WsClient {
                                                 }
                                                 Err(err) => {
                                                     if debug {
-                                                        warn!("[relaycast] Dropped typed WebSocket event: {}: {}", err, &text[..text.len().min(200)]);
+                                                        warn!("[relaycast] Dropped typed WebSocket event: {}: {}", err, truncate_str(&text, 200));
                                                     }
                                                 }
                                             }
                                         }
                                         Err(err) => {
                                             if debug {
-                                                warn!("[relaycast] Dropped non-JSON WebSocket message: {}: {}", err, &text[..text.len().min(200)]);
+                                                warn!("[relaycast] Dropped non-JSON WebSocket message: {}: {}", err, truncate_str(&text, 200));
                                             }
                                         }
                                     }
@@ -506,3 +506,29 @@ fn reconnect_delay_ms(attempt: u32, max_delay_ms: u64) -> u64 {
     let delay = 1_000u64.saturating_mul(2u64.saturating_pow(exp));
     delay.min(max_delay_ms.max(1_000))
 }
+
+fn truncate_str(s: &str, max_chars: usize) -> &str {
+    match s.char_indices().nth(max_chars) {
+        Some((idx, _)) => &s[..idx],
+        None => s,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::truncate_str;
+
+    #[test]
+    fn truncate_str_respects_utf8_boundaries() {
+        let text = "😀".repeat(201);
+        let truncated = truncate_str(&text, 200);
+
+        assert_eq!(truncated.chars().count(), 200);
+        assert!(truncated.is_char_boundary(truncated.len()));
+    }
+
+    #[test]
+    fn truncate_str_returns_short_strings_unchanged() {
+        assert_eq!(truncate_str("hello", 200), "hello");
+    }
+}