Files
homelab/pkgs/luna-voice/src/brain.rs
T
darmanandClaude Opus 5.5 ed2ce8fafc feat(terra): stored Hermes sessions for luna's voice
- Each daemon run creates a Hermes session (source "desktop") on its
  first turn, so voice chats show in the dashboard's default Chats view.
  Hermes only allows a fixed set of sources; unknown ones become the
  hidden api_server.
- Turns carry X-Hermes-Session-Id (Hermes keeps the transcript) and
  X-Hermes-Session-Key: voice (one Honcho memory session for voice).
- With a stored session only the base prompt and what's new since her
  last reply are sent; falls back to full client-side history if the
  session can't be created.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-02 18:53:12 +02:00

242 lines
8.1 KiB
Rust

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<String>) -> Self {
Message { role: "user".into(), content: content.into() }
}
pub fn assistant(content: impl Into<String>) -> Self {
Message { role: "assistant".into(), content: content.into() }
}
pub fn system(content: impl Into<String>) -> 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<String> {
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<Message> {
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<String>,
) -> Result<String> {
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<String> {
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<String> {
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<String> {
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());
}
}