Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

12.9 KB
Raw Blame
//! [`ProfileHandle`]: one open profile, and the calls a user makes on it.

use std::future::Future;
use std::path::Path;
use std::sync::Arc;

use openhuman_core::core::envelope::ApiEnvelope;
use openhuman_core::core::runtime::CoreContext;
use openhuman_core::profiles::Profile;
use openhuman_core::threads::{
    AppendConversationMessageRequest, ConversationMessagesRequest, ConversationMessagesResponse,
    ConversationThreadsListResponse,
};
use openhuman_core::web_chat::WebChannelEvent;
use serde::de::DeserializeOwned;
use serde::{Deserialize, Serialize};
use tokio::sync::broadcast;

#[cfg(feature = "channels")]
use super::RelayMessage;
use super::{
    ConversationMessageRecord, ConversationThreadSummary, Inner, ProfileError, ProfileId,
    ScopedWebEvent,
};
use crate::call::call_in;
use crate::error::CoreError;

const THREADS_UPSERT: &str = "openhuman.threads_upsert";
const THREADS_MESSAGE_APPEND: &str = "openhuman.threads_message_append";
const THREADS_LIST: &str = "openhuman.threads_list";
const THREADS_MESSAGES_LIST: &str = "openhuman.threads_messages_list";
const CHANNEL_WEB_CHAT: &str = "openhuman.channel_web_chat";
#[cfg(feature = "channels")]
const CHANNEL_RELAY_INBOUND: &str = "openhuman.channel_relay_inbound";

/// An open profile. Every call runs under the profile's own context, as a
/// gateway request for that user would.
///
/// Holding a handle (or any clone of it) keeps the profile **in use**: it is
/// never evicted or released from under you. Drop every handle to let it go
/// idle.
#[derive(Clone)]
pub struct ProfileHandle {
    runtime: Arc<Inner>,
    profile: Arc<Profile>,
    client_id: String,
}

impl std::fmt::Debug for ProfileHandle {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        f.debug_struct("ProfileHandle")
            .field("id", &self.profile.id)
            .finish_non_exhaustive()
    }
}

/// The final answer of one [`ProfileHandle::chat`] turn.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ChatReply {
    /// The thread the turn ran on.
    pub thread_id: String,
    /// The turn's request id, as its events carry it.
    pub request_id: String,
    /// The assistant's full reply.
    pub text: String,
}

/// What `channel_relay_inbound` answered: the message was accepted (its turn
/// runs in the background) or was a duplicate of one already recorded.
#[cfg(feature = "channels")]
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
pub struct RelayAccepted {
    /// Whether a turn was started for it.
    #[serde(default)]
    pub accepted: bool,
    /// The message id was already recorded on its thread; nothing ran.
    #[serde(default)]
    pub duplicate: bool,
    /// The `channel:` thread the message is on.
    pub thread_id: String,
    /// The request id the reply events carry (absent for a duplicate).
    #[serde(default)]
    pub request_id: Option<String>,
    /// The client id the reply events are addressed to.
    #[serde(default)]
    pub client_id: Option<String>,
}

/// This profile's live events: chat progress, `chat_done` / `chat_error`,
/// and the `channel_outbound` replies a gateway delivers to hosted chat
/// platforms. Only events stamped with this profile get through, the same
/// filter the gateway's `/events` stream applies.
pub struct ProfileEvents {
    profile: String,
    rx: broadcast::Receiver<ScopedWebEvent>,
}

impl ProfileEvents {
    /// The next event of this profile, or `None` once the bus is gone.
    /// Events the receiver fell too far behind on are skipped.
    pub async fn recv(&mut self) -> Option<ScopedWebEvent> {
        loop {
            match self.rx.recv().await {
                Ok(event) if event.belongs_to_profile(&self.profile) => return Some(event),
                Ok(_) => {}
                Err(broadcast::error::RecvError::Lagged(skipped)) => {
                    log::warn!(
                        "[embed][profiles] event receiver of profile={} lagged by {skipped}",
                        self.profile
                    );
                }
                Err(broadcast::error::RecvError::Closed) => return None,
            }
        }
    }
}

#[derive(Serialize)]
struct WebChatParams<'a> {
    client_id: &'a str,
    thread_id: &'a str,
    message: &'a str,
}

/// `threads.upsert` params. The controller's schema lists only these three
/// as required and refuses an explicit `null` for the optional ones.
#[derive(Serialize)]
struct UpsertThread<'a> {
    id: &'a str,
    title: &'a str,
    created_at: String,
}

#[derive(Deserialize)]
struct WebChatAccepted {
    request_id: String,
}

impl ProfileHandle {
    pub(super) fn new(runtime: Arc<Inner>, profile: Arc<Profile>) -> Self {
        let client_id = format!("embed-{}", uuid::Uuid::new_v4().simple());
        Self {
            runtime,
            profile,
            client_id,
        }
    }

    /// The profile's id.
    pub fn id(&self) -> &ProfileId {
        &self.profile.id
    }

    /// The profile's workspace (threads, memory, transcripts, ledgers).
    pub fn workspace_dir(&self) -> &Path {
        &self.profile.layout.workspace_dir
    }

    /// The client id this handle's web-chat turns are addressed to.
    pub fn client_id(&self) -> &str {
        &self.client_id
    }

    /// The context every call on this handle runs under.
    pub fn context(&self) -> &Arc<CoreContext> {
        self.profile.context()
    }

    /// Run `fut` as this profile: anything the core does inside it resolves
    /// this user's config, workspace, storage scope and policy.
    pub async fn scope<F: Future>(&self, fut: F) -> F::Output {
        CoreContext::scope(Arc::clone(self.profile.context()), fut).await
    }

    /// Dispatch an RPC `method` as this user. Only the reviewed user surface
    /// (`profiles::surface::USER_METHODS`) is reachable; anything else
    /// answers as an unknown method, exactly as through the gateway.
    pub async fn call<P, R>(&self, method: &'static str, params: P) -> Result<R, CoreError>
    where
        P: Serialize,
        R: DeserializeOwned,
    {
        call_in(
            &self.runtime.core,
            Arc::clone(self.profile.context()),
            method,
            params,
        )
        .await
    }

    /// Subscribe to this profile's events. Subscribe before starting the
    /// work whose events you want: earlier events are not replayed.
    pub fn events(&self) -> ProfileEvents {
        ProfileEvents {
            profile: self.profile.id.to_string(),
            rx: openhuman_core::web_chat::subscribe_web_channel_events(),
        }
    }

    /// Send `text` on `thread_id` (created if it does not exist yet) and wait
    /// for the turn's final reply. A thread id is unique per profile: two
    /// users' `t1` are two threads.
    ///
    /// Like the web app, it records the user's message on the thread itself
    /// (`threads_message_append`) before starting the turn; the core records
    /// the reply.
    ///
    /// Waits for as long as the turn runs; wrap it in
    /// `tokio::time::timeout` to bound it. For live progress, read
    /// [`events`](Self::events) alongside.
    pub async fn chat(&self, thread_id: &str, text: &str) -> Result<ChatReply, ProfileError> {
        self.ensure_thread(thread_id).await?;
        self.append_user_message(thread_id, text).await?;
        let mut events = self.events();
        let accepted: WebChatAccepted = self
            .call(
                CHANNEL_WEB_CHAT,
                WebChatParams {
                    client_id: &self.client_id,
                    thread_id,
                    message: text,
                },
            )
            .await?;
        let request_id = accepted.request_id;
        log::debug!(
            "[embed][profiles] chat started profile={} thread_id={thread_id} request_id={request_id}",
            self.profile.id
        );
        loop {
            let Some(event) = events.recv().await else {
                return Err(ProfileError::EventsClosed);
            };
            let context = event.context();
            if context.thread_id != thread_id || context.request_id != request_id {
                continue;
            }
            match event.wire_event() {
                WebChannelEvent::ChatDone { full_response, .. } => {
                    log::debug!(
                        "[embed][profiles] chat done profile={} request_id={request_id}",
                        self.profile.id
                    );
                    return Ok(ChatReply {
                        thread_id: thread_id.to_string(),
                        request_id,
                        text: chat_reply_text(full_response.clone()),
                    });
                }
                WebChannelEvent::ChatError {
                    message,
                    error_type,
                    ..
                } => {
                    log::debug!(
                        "[embed][profiles] chat failed profile={} request_id={request_id} error_type={:?}",
                        self.profile.id,
                        error_type
                    );
                    return Err(ProfileError::Turn {
                        message: chat_failure_message(message.clone()),
                        error_type: error_type.clone(),
                    });
                }
                WebChannelEvent::ChatCancelled { .. } => {
                    return Err(ProfileError::Cancelled);
                }
                _ => {}
            }
        }
    }

    /// Hand the core a message the host received for this user on a hosted
    /// chat platform (Telegram, iMessage, ...). It lands on the user's
    /// `channel:<channel>/<sender>/<chat>` thread and its turn runs in the
    /// background; the reply arrives on [`events`](Self::events) as a
    /// `channel_outbound` event for the host to deliver. A message id already
    /// recorded is acknowledged as a duplicate and runs nothing.
    #[cfg(feature = "channels")]
    pub async fn relay_inbound(
        &self,
        message: RelayMessage,
    ) -> Result<RelayAccepted, ProfileError> {
        let accepted: RelayAccepted = self.call(CHANNEL_RELAY_INBOUND, message).await?;
        log::debug!(
            "[embed][profiles] relay profile={} accepted={} duplicate={}",
            self.profile.id,
            accepted.accepted,
            accepted.duplicate
        );
        Ok(accepted)
    }

    /// The profile's threads, web and relayed alike.
    pub async fn threads(&self) -> Result<Vec<ConversationThreadSummary>, ProfileError> {
        let listed: ApiEnvelope<ConversationThreadsListResponse> =
            self.call(THREADS_LIST, serde_json::json!({})).await?;
        Ok(listed.data.map(|data| data.threads).unwrap_or_default())
    }

    /// The messages on this profile's `thread_id`.
    pub async fn messages(
        &self,
        thread_id: &str,
    ) -> Result<Vec<ConversationMessageRecord>, ProfileError> {
        let listed: ApiEnvelope<ConversationMessagesResponse> = self
            .call(
                THREADS_MESSAGES_LIST,
                ConversationMessagesRequest {
                    thread_id: thread_id.to_string(),
                },
            )
            .await?;
        Ok(listed.data.map(|data| data.messages).unwrap_or_default())
    }

    /// Record `text` as the user's message on `thread_id`.
    async fn append_user_message(&self, thread_id: &str, text: &str) -> Result<(), ProfileError> {
        let _appended: ApiEnvelope<ConversationMessageRecord> = self
            .call(
                THREADS_MESSAGE_APPEND,
                AppendConversationMessageRequest {
                    thread_id: thread_id.to_string(),
                    message: ConversationMessageRecord {
                        id: format!("msg_{}", uuid::Uuid::new_v4()),
                        content: text.to_string(),
                        attachments: Vec::new(),
                        message_type: "text".to_string(),
                        extra_metadata: serde_json::json!({}),
                        sender: "user".to_string(),
                        created_at: chrono::Utc::now().to_rfc3339(),
                    },
                    attachments: Vec::new(),
                },
            )
            .await?;
        Ok(())
    }

    /// Create `thread_id` on this profile unless it exists (`threads_upsert`
    /// keeps an existing thread as it is).
    async fn ensure_thread(&self, thread_id: &str) -> Result<(), ProfileError> {
        let _summary: ApiEnvelope<ConversationThreadSummary> = self
            .call(
                THREADS_UPSERT,
                UpsertThread {
                    id: thread_id,
                    title: thread_id,
                    created_at: chrono::Utc::now().to_rfc3339(),
                },
            )
            .await?;
        Ok(())
    }
}

fn chat_reply_text(full_response: Option<String>) -> String {
    full_response.unwrap_or_default()
}

fn chat_failure_message(message: Option<String>) -> String {
    message.unwrap_or_else(|| "The turn failed without an error message.".to_string())
}

#[cfg(test)]
#[path = "handle_tests.rs"]
mod tests;