use anyhow::{bail, Result}; use futures_util::StreamExt; use serde::{Deserialize, Serialize}; use tokio::sync::mpsc; #[derive(Clone, Serialize, Deserialize, Debug)] pub struct Message { pub role: String, pub content: String, } impl Message { pub fn user(content: impl Into) -> Self { Message { role: "user".into(), content: content.into() } } pub fn assistant(content: impl Into) -> Self { Message { role: "assistant".into(), content: content.into() } } pub fn system(content: impl Into) -> Self { Message { role: "system".into(), content: content.into() } } } /// Where a turn lands in Hermes. `id` makes Hermes keep the history (and list /// the session on the dashboard); `key` scopes long-term memory per channel. #[derive(Clone, Copy, Default)] pub struct Session<'a> { pub id: Option<&'a str>, pub key: Option<&'a str>, } /// Creates a stored Hermes session. The source is only a dashboard label — /// Hermes allowlists it, and anything unknown becomes the hidden `api_server`. pub async fn create_session( client: &reqwest::Client, base_url: &str, key: &str, source: &str, ) -> Result { let resp = client .post(format!("{}/api/sessions", base_url.trim_end_matches('/'))) .bearer_auth(key) .json(&serde_json::json!({ "source": source })) .send() .await?; if !resp.status().is_success() { let status = resp.status(); let text = resp.text().await.unwrap_or_default(); bail!("hermes session create {status}: {}", text.trim()); } let v: serde_json::Value = resp.json().await?; match v.pointer("/session/id").and_then(|id| id.as_str()) { Some(id) => Ok(id.to_string()), None => bail!("hermes session create: no id in response"), } } /// What to send for the next turn. With a stored session Hermes loads the /// history itself and folds every system message into the prompt, so only the /// base prompt plus what's new since her last reply goes out — resending old /// notes would repeat them every turn. pub fn outgoing(history: &[Message], stored: bool) -> Vec { let Some(last) = history.iter().rposition(|m| m.role == "assistant") else { return history.to_vec(); }; if !stored { return history.to_vec(); } let base = history.first().filter(|m| m.role == "system").cloned(); base.into_iter().chain(history[last + 1..].iter().cloned()).collect() } /// Streams a reply from Hermes' OpenAI-compatible API, pushing text deltas /// into `tx` as they arrive. /// /// /v1/chat/completions, not /v1/responses: this shape is the one every OpenAI /// client exercises, so it is the least likely to differ between Hermes /// versions. With `session.id` set Hermes keeps the transcript itself. pub async fn stream_reply( client: &reqwest::Client, base_url: &str, key: &str, model: &str, history: &[Message], session: Session<'_>, tx: mpsc::Sender, ) -> Result { let body = serde_json::json!({ "model": model, "messages": history, "stream": true, }); let mut req = client .post(format!("{}/v1/chat/completions", base_url.trim_end_matches('/'))) .bearer_auth(key) .json(&body); if let Some(id) = session.id { req = req.header("X-Hermes-Session-Id", id); } if let Some(k) = session.key { req = req.header("X-Hermes-Session-Key", k); } let resp = req.send().await?; if !resp.status().is_success() { let status = resp.status(); let text = resp.text().await.unwrap_or_default(); bail!("hermes {status}: {}", text.trim()); } let mut stream = resp.bytes_stream(); let mut pending = String::new(); let mut full = String::new(); while let Some(chunk) = stream.next().await { pending.push_str(&String::from_utf8_lossy(&chunk?)); // SSE frames are separated by a blank line; a chunk boundary can land // mid-frame, so only complete frames are consumed. while let Some(idx) = pending.find("\n\n") { let frame: String = pending.drain(..idx + 2).collect(); for line in frame.lines() { let Some(data) = line.strip_prefix("data:") else { continue }; let data = data.trim(); if data == "[DONE]" { return nonempty(full); } if let Some(msg) = parse_error(data) { bail!("hermes: {msg}"); } if let Some(delta) = parse_delta(data) { full.push_str(&delta); // A closed receiver means the reply was cancelled (barge-in). if tx.send(delta).await.is_err() { return Ok(full); } } } } } nonempty(full) } /// Hermes answers a failed upstream call with 200 and an empty stream, so an /// empty reply is the only sign of e.g. a dead provider key. fn nonempty(full: String) -> Result { if full.trim().is_empty() { bail!("hermes returned an empty reply (check its log on mars)"); } Ok(full) } /// An `{"error": ...}` frame, as OpenAI-compatible servers send mid-stream. fn parse_error(data: &str) -> Option { let v: serde_json::Value = serde_json::from_str(data).ok()?; let err = v.get("error")?; Some( err.get("message") .and_then(|m| m.as_str()) .map(str::to_string) .unwrap_or_else(|| err.to_string()), ) } /// Pulls choices[0].delta.content out of one SSE data payload. Tool-call /// frames and role-only frames carry no content and are skipped. fn parse_delta(data: &str) -> Option { let v: serde_json::Value = serde_json::from_str(data).ok()?; let content = v .get("choices")? .get(0)? .get("delta")? .get("content")? .as_str()?; (!content.is_empty()).then(|| content.to_string()) } #[cfg(test)] mod tests { use super::{nonempty, outgoing, parse_delta, parse_error, Message}; fn roles(msgs: &[Message]) -> Vec<(&str, &str)> { msgs.iter().map(|m| (m.role.as_str(), m.content.as_str())).collect() } #[test] fn stored_session_sends_prompt_and_only_whats_new() { let h = vec![ Message::system("prompt"), Message::user("one"), Message::assistant("reply"), Message::system("[interrupted]"), Message::user("two"), ]; assert_eq!( roles(&outgoing(&h, true)), [("system", "prompt"), ("system", "[interrupted]"), ("user", "two")] ); assert_eq!(outgoing(&h, false).len(), 5); } #[test] fn first_turn_sends_everything_either_way() { let h = vec![Message::system("prompt"), Message::user("one")]; assert_eq!(outgoing(&h, true).len(), 2); let bare = vec![Message::user("one")]; assert_eq!(roles(&outgoing(&bare, true)), [("user", "one")]); } #[test] fn error_frame_carries_its_message() { let d = r#"{"error":{"type":"api_error","message":"Invalid credential"}}"#; assert_eq!(parse_error(d).as_deref(), Some("Invalid credential")); assert!(parse_error(r#"{"choices":[{"delta":{"content":"hi"}}]}"#).is_none()); } #[test] fn empty_reply_is_an_error() { assert!(nonempty(" \n".into()).is_err()); assert_eq!(nonempty("hi".into()).unwrap(), "hi"); } #[test] fn extracts_content_delta() { let d = r#"{"choices":[{"delta":{"content":"hi"}}]}"#; assert_eq!(parse_delta(d).as_deref(), Some("hi")); } #[test] fn ignores_role_only_and_tool_frames() { assert!(parse_delta(r#"{"choices":[{"delta":{"role":"assistant"}}]}"#).is_none()); assert!(parse_delta(r#"{"choices":[{"delta":{"tool_calls":[]}}]}"#).is_none()); assert!(parse_delta(r#"{"choices":[{"delta":{"content":""}}]}"#).is_none()); } #[test] fn ignores_malformed_json_rather_than_failing_the_stream() { assert!(parse_delta("not json").is_none()); assert!(parse_delta("{}").is_none()); } }