The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.
Rust agent-orchestrationai-agentsai-assistantdesktopllmlocal-firstmcppersonal-aiprivacyrustsecond-braintauri
//! Identity-scoped implementation of TinyChannels' host callbacks (durable state goes through the storage bus).
use crate::channels::context::ChannelRuntimeContext;
use crate::channels::runtime::dispatch::RuntimeChannelMessage;
use crate::config::Config;
use std::collections::HashMap;
use std::sync::{Arc, OnceLock, Weak};
use tinybus::{Error, Result};
use tinychannels_bus::module_progressive::{
ProgressiveTransportRequest, ProgressiveTransportResult,
};
use tinychannels_bus::{
ChannelBackendRequest, ChannelBackendResult, HostEventPublication, HostSpeechSynthesisRequest,
HostSpeechSynthesisResult, HostTranscriptionRequest, HostTranscriptionResult,
HostVoiceReplyPolicy, HostVoiceReplyPolicyRequest, HostVoiceTranscriptionRequest,
};
use tokio::sync::mpsc;
const MAX_CALLBACK_BYTES: usize = 128 * 1024;
const MAX_TRANSCRIPTION_BYTES: usize = 12 * 1024 * 1024;
const MAX_VOICE_MEDIA_BYTES: usize = 12 * 1024 * 1024;
const MAX_VOICE_MEDIA_DECODED_BYTES: usize = 8 * 1024 * 1024;
const MAX_CONTROLLER_BYTES: usize = 1024 * 1024;
type ProgressiveChannelRegistry =
Arc<OnceLock<Arc<HashMap<String, Weak<dyn ProgressiveChannelTransport>>>>>;
#[async_trait::async_trait]
pub(super) trait ProgressiveChannelTransport: Send + Sync {
fn configured_name(&self) -> &str;
async fn dispatch_progressive(
&self,
request: ProgressiveTransportRequest,
) -> Result<ProgressiveTransportResult>;
}
#[async_trait::async_trait]
pub(super) trait ProgressiveOutputObserver: Send + Sync {
async fn observe(
&self,
channel: &tinychannels_bus::ChannelRef,
conversation: &tinychannels_bus::ConversationRef,
turn_id: &str,
sequence: u64,
event: &tinychannels_bus::module_progressive::ChannelOutputEvent,
) -> Result<()>;
}
/// Callbacks capture one immutable host config and a weak runtime context.
/// The weak reference avoids a cycle from runtime context -> module channel ->
/// lease -> TinyBus connection -> callback -> runtime context.
pub(super) struct ChannelHostCallbacks {
config: Arc<Config>,
core_context: Option<Arc<crate::core::runtime::CoreContext>>,
tenant: crate::core::runtime::Tenant,
cancellation: tokio_util::sync::CancellationToken,
context: Arc<OnceLock<Weak<ChannelRuntimeContext>>>,
progressive_channels: ProgressiveChannelRegistry,
output_observer: Option<Arc<dyn ProgressiveOutputObserver>>,
dispatch: mpsc::Sender<RuntimeChannelMessage>,
}
impl ChannelHostCallbacks {
pub(super) fn new(
ctx: &crate::core::runtime::DispatchCtx,
config: Arc<Config>,
context: Arc<OnceLock<Weak<ChannelRuntimeContext>>>,
progressive_channels: ProgressiveChannelRegistry,
output_observer: Option<Arc<dyn ProgressiveOutputObserver>>,
dispatch: mpsc::Sender<RuntimeChannelMessage>,
) -> Self {
Self {
config,
core_context: ctx.resolved(),
tenant: crate::core::runtime::tenant::isolated_unless_tenant(
ctx.tenant(),
"channel_host_callback",
),
cancellation: crate::channels::runtime::session::channel_session(),
context,
progressive_channels,
output_observer,
dispatch,
}
}
fn validate_callback_size<T: serde::Serialize>(value: &T) -> Result<()> {
if serde_json::to_vec(value).map_or(true, |bytes| bytes.len() > MAX_CALLBACK_BYTES) {
return Err(Error::failed("host callback payload exceeds its limit"));
}
Ok(())
}
fn voice(&self) -> crate::channels::host::voice::ChannelVoiceHost {
crate::channels::host::voice::ChannelVoiceHost {
config: Arc::clone(&self.config),
}
}
fn context(&self) -> Result<Arc<ChannelRuntimeContext>> {
self.context
.get()
.and_then(Weak::upgrade)
.ok_or_else(|| Error::failed("channel runtime is stopping"))
}
}
#[tinybus::interface(name = "ai.tinyhumans.tinychannels.ChannelsHost")]
impl ChannelHostCallbacks {
async fn deliver_inbound(&self, channel: String, message: serde_json::Value) -> Result<()> {
tracing::debug!(channel, "[channels] module invoked inbound callback");
Self::validate_callback_size(&message)?;
let relay_shaped = message.get("envelope").is_some()
|| message.get("delivered_via_authenticated_relay").is_some();
if relay_shaped {
let delivery = serde_json::from_value::<
tinychannels_bus::module_relay::RelayInboundDelivery,
>(message.clone())
.map_err(|_| Error::failed("invalid relay delivery"))?;
if delivery.envelope.channel.id != channel {
return Err(Error::failed(
"relay callback channel does not match envelope",
));
}
self.dispatch
.send(RuntimeChannelMessage::from_authenticated_relay(delivery))
.await
.map_err(|_| Error::failed("channel dispatch is closed"))?;
return Ok(());
}
// v22 providers deliver the normalized envelope directly through the
// same host callback. Keep it intact until module preparation derives
// the legacy prompt projection and scoped identity. A typed-looking
// payload must never fall through and be reinterpreted as v21 text.
let typed_envelope = message
.get("channel")
.is_some_and(serde_json::Value::is_object)
|| ["conversation", "parts", "access"]
.iter()
.any(|field| message.get(*field).is_some());
if typed_envelope {
let envelope: tinychannels_bus::ChannelInboundEnvelope =
serde_json::from_value(message)
.map_err(|_| Error::failed("invalid inbound envelope"))?;
let channel_present = !channel.trim().is_empty();
let provider_matches = envelope.channel.id == tinychannels_bus::provider_id(&channel);
let account_matches = envelope.channel.account_id.as_deref() == Some(channel.as_str());
let conversation_present = !envelope.conversation.id.trim().is_empty();
let message_present = !envelope.message_id.trim().is_empty();
tracing::debug!(
channel_present,
provider_matches,
account_matches,
conversation_present,
message_present,
"typed inbound envelope scope validation"
);
if !channel_present
|| !provider_matches
|| !account_matches
|| envelope.message_id.trim().is_empty()
|| envelope.conversation.id.trim().is_empty()
{
return Err(Error::failed("inbound envelope identity is invalid"));
}
self.dispatch
.send(RuntimeChannelMessage::with_inbound_envelope(
tinychannels_bus::ChannelMessage::default(),
envelope,
))
.await
.map_err(|_| Error::failed("channel dispatch is closed"))?;
return Ok(());
}
let message: tinychannels_bus::ChannelMessage = serde_json::from_value(message)
.map_err(|_| Error::failed("invalid inbound message"))?;
if message.channel != channel {
return Err(Error::failed("callback channel does not match message"));
}
tracing::debug!(channel, message_id = %message.id, "[channels] module delivered inbound message");
self.dispatch
.send(RuntimeChannelMessage::from(message))
.await
.map_err(|_| Error::failed("channel dispatch is closed"))
}
async fn report_status(
&self,
channel: String,
state: String,
_detail: Option<String>,
) -> Result<()> {
if channel.is_empty() || channel.len() > 256 || state.len() > 128 {
return Err(Error::failed("channel status is invalid"));
}
match state.as_str() {
"connected" => crate::core::bus::BUS
.publish(crate::core::events::DomainEvent::ChannelConnected { channel }),
"disconnected" | "stopped" => crate::core::bus::BUS.publish(
crate::core::events::DomainEvent::ChannelDisconnected {
channel,
reason: state,
},
),
// `connecting`, `reconnecting`, and `unhealthy` are health facts,
// not user-facing lifecycle events.
_ => {}
}
Ok(())
}
async fn persist_allowed_identity(&self, channel: String, identity: String) -> Result<()> {
crate::channels::host::ConfigAllowlistStore
.persist_allowed_identity(&channel, &identity)
.await
.map_err(|_| Error::failed("channel identity persistence failed"))
}
async fn transcribe(
&self,
request: HostTranscriptionRequest,
) -> Result<HostTranscriptionResult> {
if serde_json::to_vec(&request).map_or(true, |bytes| bytes.len() > MAX_TRANSCRIPTION_BYTES)
{
return Err(Error::failed("transcription callback exceeds its limit"));
}
self.voice()
.transcribe_host(request)
.await
.map_err(|_| Error::failed("channel transcription failed"))
}
async fn transcribe_voice(
&self,
request: HostVoiceTranscriptionRequest,
) -> Result<HostTranscriptionResult> {
if serde_json::to_vec(&request).map_or(true, |bytes| bytes.len() > MAX_TRANSCRIPTION_BYTES)
{
return Err(Error::failed("transcription callback exceeds its limit"));
}
self.voice()
.transcribe_voice(request)
.await
.map_err(|_| Error::failed("channel transcription failed"))
}
async fn synthesize_speech(
&self,
request: HostSpeechSynthesisRequest,
) -> Result<HostSpeechSynthesisResult> {
Self::validate_callback_size(&request)?;
self.voice()
.synthesize_speech(request)
.await
.map_err(|_| Error::failed("channel speech synthesis failed"))
}
async fn store_voice_media(
&self,
request: tinychannels_bus::HostStoreVoiceMediaRequest,
) -> Result<tinychannels_bus::HostStoreVoiceMediaResult> {
let serialized_len = serde_json::to_vec(&request).map_or(usize::MAX, |bytes| bytes.len());
tracing::debug!(
direction = ?request.direction,
base64_len = request.audio_base64.len(),
serialized_within_limit = serialized_len <= MAX_VOICE_MEDIA_BYTES,
"scoped channel voice media callback entered"
);
if serialized_len > MAX_VOICE_MEDIA_BYTES {
tracing::debug!(
reason = "serialized_size",
"scoped channel voice media rejected"
);
return Err(Error::failed("voice media callback exceeds its limit"));
}
let decoded = base64::Engine::decode(
&base64::engine::general_purpose::STANDARD,
&request.audio_base64,
)
.map_err(|_| {
tracing::debug!(
reason = "invalid_base64",
"scoped channel voice media rejected"
);
Error::failed("voice media payload is invalid")
})?;
if decoded.is_empty() || decoded.len() > MAX_VOICE_MEDIA_DECODED_BYTES {
tracing::debug!(
reason = "decoded_size",
"scoped channel voice media rejected"
);
return Err(Error::failed("voice media exceeds its size limit"));
}
let scope = &request.scope;
let context = self.context()?;
let Some(channel) = context.channels_by_name.get(&scope.configured_instance) else {
tracing::debug!(
reason = "configured_instance_not_registered",
provider_adapter_registered =
context.channels_by_name.contains_key(&scope.channel.id),
provider_matches_instance =
scope.channel.id == tinychannels_bus::provider_id(&scope.configured_instance),
account_matches_instance =
scope.channel.account_id.as_deref() == Some(scope.configured_instance.as_str()),
"scoped channel voice media rejected"
);
return Err(Error::failed("voice media account is not configured"));
};
if scope.configured_instance.trim().is_empty()
|| scope.channel.id != tinychannels_bus::provider_id(&scope.configured_instance)
|| scope.channel.account_id.as_deref() != Some(scope.configured_instance.as_str())
|| tinychannels_bus::provider_id(channel.name()) != scope.channel.id
|| scope.conversation.id.trim().is_empty()
|| scope.turn_id.trim().is_empty()
{
tracing::debug!(
reason = "scope_mismatch",
provider_matches_instance =
scope.channel.id == tinychannels_bus::provider_id(&scope.configured_instance),
account_matches_instance =
scope.channel.account_id.as_deref() == Some(scope.configured_instance.as_str()),
adapter_matches_provider =
tinychannels_bus::provider_id(channel.name()) == scope.channel.id,
conversation_present = !scope.conversation.id.trim().is_empty(),
turn_present = !scope.turn_id.trim().is_empty(),
"scoped channel voice media rejected"
);
return Err(Error::failed(
"voice media scope does not match configured account",
));
}
// The TinyChannels module persists and serves voice media itself
// (`BeginMediaRead`); this callback is only a one-release compatibility
// seam for older modules, and the host holds no durable store for it.
tracing::debug!(
reason = "module_owned_media",
"scoped channel voice media store declined"
);
Err(Error::failed(
"voice media is stored by the channels module",
))
}
async fn get_voice_reply_policy(
&self,
request: HostVoiceReplyPolicyRequest,
) -> Result<HostVoiceReplyPolicy> {
Self::validate_callback_size(&request)?;
Ok(self.voice().reply_policy(&request))
}
async fn publish_event(&self, publication: HostEventPublication) -> Result<()> {
Self::validate_callback_size(&publication)?;
crate::channels::host::OpenHumanEventSink
.publish_host(&publication.domain, &publication.kind, publication.payload)
.await
.map_err(|_| Error::failed("channel event publication failed"))
}
async fn dispatch_controller_backend(
&self,
request: ChannelBackendRequest,
) -> Result<ChannelBackendResult> {
if serde_json::to_vec(&request).map_or(true, |bytes| bytes.len() > MAX_CONTROLLER_BYTES) {
return Err(Error::failed("controller callback exceeds its limit"));
}
match request {
ChannelBackendRequest::RemoteControl(request) => {
let context = self.context()?;
let tenant = &self.tenant;
let cancellation = &self.cancellation;
// The captured context is the carrier; without one the host's
// default context (none in SaaS, which fails closed).
let dispatch_ctx = match &self.core_context {
Some(core) => crate::core::runtime::DispatchCtx::new(Arc::clone(core)),
None => crate::core::runtime::DispatchCtx::host_default(),
};
let dispatch = async {
tokio::select! {
biased;
_ = cancellation.cancelled() => {
Err(Error::failed("channel session ended"))
}
result = crate::channels::host::remote_control::dispatch_callback(
&dispatch_ctx,
context.as_ref(),
tenant,
cancellation,
None,
request,
) => result.map(ChannelBackendResult::RemoteControl),
}
};
match &self.core_context {
Some(core_context) => {
crate::core::runtime::CoreContext::scope(Arc::clone(core_context), dispatch)
.await
}
None => dispatch.await,
}
}
ChannelBackendRequest::ProgressiveTransport(request) => self
.dispatch_progressive_transport(*request)
.await
.map(|result| ChannelBackendResult::ProgressiveTransport(Box::new(result))),
request => {
crate::channels::controllers::OpenHumanChannelBackend::new((*self.config).clone())
.dispatch_callback(request)
.await
.map_err(|_| Error::failed("channel controller callback failed"))
}
}
}
}
#[cfg(test)]
#[path = "callback_tests.rs"]
mod tests;
impl ChannelHostCallbacks {
async fn dispatch_progressive_transport(
&self,
request: ProgressiveTransportRequest,
) -> Result<ProgressiveTransportResult> {
if self.cancellation.is_cancelled() {
return Err(Error::failed("channel session ended"));
}
if let ProgressiveTransportRequest::OutputEvent {
channel: route,
channel_ref,
conversation,
turn_id,
sequence,
event,
..
} = &request
{
if self.cancellation.is_cancelled() {
return Err(Error::failed("channel session ended"));
}
let channel = channel_ref
.as_ref()
.ok_or_else(|| Error::failed("progressive output channel identity is required"))?;
let conversation = conversation.as_ref().ok_or_else(|| {
Error::failed("progressive output conversation identity is required")
})?;
let turn_id = turn_id
.as_deref()
.ok_or_else(|| Error::failed("progressive output turn identity is required"))?;
if conversation.id.is_empty() || turn_id.is_empty() {
return Err(Error::failed("progressive output scope is invalid"));
}
self.progressive_channel(route, Some(channel))?;
if let Some(observer) = &self.output_observer {
observer
.observe(channel, conversation, turn_id, *sequence, event)
.await?;
}
return Ok(ProgressiveTransportResult::Acknowledged);
}
let (channel, channel_ref) = match &request {
ProgressiveTransportRequest::OutputEvent {
channel,
channel_ref,
..
}
| ProgressiveTransportRequest::Send {
channel,
channel_ref,
..
}
| ProgressiveTransportRequest::SendTyped {
channel,
channel_ref,
..
}
| ProgressiveTransportRequest::Edit {
channel,
channel_ref,
..
}
| ProgressiveTransportRequest::Delete {
channel,
channel_ref,
..
}
| ProgressiveTransportRequest::Typing {
channel,
channel_ref,
..
} => (channel.as_str(), channel_ref.as_ref()),
};
self.progressive_channel(channel, channel_ref)?
.dispatch_progressive(request)
.await
}
fn progressive_channel(
&self,
channel: &str,
channel_ref: Option<&tinychannels_bus::ChannelRef>,
) -> Result<Arc<dyn ProgressiveChannelTransport>> {
let reference = channel_ref.ok_or_else(|| Error::failed("channel account is required"))?;
let account = reference
.account_id
.as_deref()
.ok_or_else(|| Error::failed("configured channel account is required"))?;
let adapters = self
.progressive_channels
.get()
.ok_or_else(|| Error::failed("progressive channel adapters are unavailable"))?;
let adapter = adapters
.get(account)
.and_then(Weak::upgrade)
.ok_or_else(|| Error::failed("configured channel account is unavailable"))?;
let configured_provider =
tinychannels_bus::capabilities::provider_id(adapter.configured_name());
if configured_provider != reference.id
|| tinychannels_bus::capabilities::provider_id(channel) != reference.id
{
return Err(Error::failed(
"configured channel account does not match request",
));
}
Ok(adapter)
}
}