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
//! The host's adapter between a web-chat turn and TinyChannels' web projection
//! module. Canonical output crosses TinyBus; the host retains event delivery,
//! tenant routing, and web-chat-specific lifecycle policy.
use std::sync::Arc;
use sha2::Digest as _;
use tinychannels_bus::module_progressive::ChannelOutputEvent;
use tinychannels_bus::module_web_output::{
BeginWebTurn, EndWebTurn, ProjectWebOutput, WebTurnHandle,
};
use tinychannels_bus::web as bus_web;
use super::event_bus_channel::publish_web_channel_event_in;
use crate::config::Config;
use crate::core::runtime::DispatchCtx;
/// Addressing of one turn on the web wire.
#[derive(Clone, Debug)]
pub(crate) struct TurnIds {
pub(crate) client_id: String,
pub(crate) thread_id: String,
pub(crate) request_id: String,
}
struct SurfaceState {
module: Option<tinybus::module::ModuleClient>,
handle: Option<WebTurnHandle>,
closed: bool,
cleanup_done: Arc<tokio::sync::Notify>,
cleanup_runtime: Option<tokio::runtime::Handle>,
request_id: String,
}
/// One module-owned projection turn plus its host broadcast destination.
#[derive(Clone)]
pub(crate) struct Surface {
state: Arc<tokio::sync::Mutex<SurfaceState>>,
ctx: DispatchCtx,
scope_key: String,
ids: TurnIds,
sequenced: bool,
}
impl Surface {
/// A surface for the turn `ids`, publishing under `ctx`. Every canonical
/// projection goes through the compiled TinyChannels module.
pub(crate) async fn new(ctx: &DispatchCtx, ids: TurnIds, config: Config) -> Self {
#[cfg(all(test, feature = "channels", feature = "modules"))]
let module = {
let _ = config;
crate::channels::module_fixture::client().await
};
#[cfg(not(all(test, feature = "channels", feature = "modules")))]
let module = crate::modules::client(config);
let tenant = super::ops::tenant_of(ctx);
let scope_bytes =
serde_json::to_vec(&(tenant, &ids.client_id, &ids.thread_id, &ids.request_id))
.expect("web turn scope tuple is serializable");
let scope_key = format!(
"web-chat:{}",
hex::encode(sha2::Sha256::digest(scope_bytes))
);
Self {
state: Arc::new(tokio::sync::Mutex::new(SurfaceState {
module: Some(module),
handle: None,
closed: false,
cleanup_done: Arc::new(tokio::sync::Notify::new()),
cleanup_runtime: Some(tokio::runtime::Handle::current()),
request_id: ids.request_id.clone(),
})),
ctx: ctx.clone(),
scope_key,
ids,
sequenced: true,
}
}
/// Publish this surface's projections without the module's `seq`. A late
/// event projected after the turn's own projection closed gets a fresh
/// module handle whose sequence restarts, and clients drop an event whose
/// `seq` is not above the last one they saw for the request.
pub(crate) fn unsequenced(mut self) -> Self {
self.sequenced = false;
self
}
/// A host-authored terminal event does not need a module handle when the
/// turn never started canonical progress.
pub(crate) fn host_only(ctx: &DispatchCtx, ids: TurnIds) -> Self {
let tenant = super::ops::tenant_of(ctx);
let scope_bytes =
serde_json::to_vec(&(tenant, &ids.client_id, &ids.thread_id, &ids.request_id))
.expect("web turn scope tuple is serializable");
let scope_key = format!(
"web-chat:{}",
hex::encode(sha2::Sha256::digest(scope_bytes))
);
Self {
state: Arc::new(tokio::sync::Mutex::new(SurfaceState {
module: None,
handle: None,
closed: false,
cleanup_done: Arc::new(tokio::sync::Notify::new()),
cleanup_runtime: None,
request_id: ids.request_id.clone(),
})),
ctx: ctx.clone(),
scope_key,
ids,
sequenced: true,
}
}
async fn begin_if_needed(&self, state: &mut SurfaceState) -> Result<String, String> {
if state.closed {
return Err("web projection turn is already closed".to_owned());
}
if let Some(handle) = &state.handle {
return Ok(handle.handle.clone());
}
let module = state
.module
.as_ref()
.ok_or_else(|| "module client is unavailable for canonical projection".to_owned())?;
let response: WebTurnHandle = module
.call_confidential(
"tinychannels",
tinychannels_bus::methods::BEGIN_WEB_TURN,
(BeginWebTurn {
scope_key: self.scope_key.clone(),
context: self.context(),
},),
)
.await
.map_err(|error| error.to_string())?;
let handle = response.handle.clone();
state.handle = Some(response);
Ok(handle)
}
async fn end_if_needed(&self, state: &mut SurfaceState) {
state.closed = true;
let Some(handle) = state.handle.take() else {
return;
};
let Some(module) = state.module.as_ref() else {
log::warn!(
"[web-channel] projection handle has no module client request_id={}",
self.ids.request_id
);
return;
};
if let Err(error) = module
.call_confidential::<()>(
"tinychannels",
tinychannels_bus::methods::END_WEB_TURN,
(EndWebTurn {
handle: handle.handle,
},),
)
.await
{
log::warn!(
"[web-channel] projection turn cleanup failed request_id={}: {error}",
self.ids.request_id
);
}
}
/// Close a canonical projection even when a turn ended without a terminal
/// output event. Safe to call after the module already auto-closed it.
pub(crate) async fn close(&self) {
let mut state = self.state.lock().await;
self.end_if_needed(&mut state).await;
}
fn publish(
&self,
mut event: bus_web::WebChannelEvent,
interim_round: Option<u32>,
projected: bool,
) {
if projected {
event.normalize_projected_wire_fields();
}
if let bus_web::WebChannelEvent::ChatInterim { round, .. } = &mut event {
if round.is_none() {
*round = interim_round.filter(|round| *round > 0);
}
}
publish_web_channel_event_in(&self.ctx, event);
}
/// Project one canonical output event onto the web wire, in module-owned
/// sequence order. Module errors fail closed; the host never reimplements
/// the projection locally.
pub(crate) async fn output(&self, event: ChannelOutputEvent) {
self.project(event, None).await;
}
async fn project(&self, event: ChannelOutputEvent, interim_round: Option<u32>) {
let mut state = self.state.lock().await;
if state.closed {
log::debug!(
"[web-channel] dropping output after terminal request_id={}",
self.ids.request_id
);
return;
}
let handle = match self.begin_if_needed(&mut state).await {
Ok(handle) => handle,
Err(error) => {
log::warn!(
"[web-channel] projection turn could not begin request_id={}: {error}",
self.ids.request_id
);
return;
}
};
let Some(module) = state.module.as_ref() else {
log::warn!(
"[web-channel] output event has no module client request_id={}",
self.ids.request_id
);
return;
};
let projected: tinychannels_bus::module_web_output::WebOutputEvents = match module
.call_confidential(
"tinychannels",
tinychannels_bus::methods::PROJECT_WEB_OUTPUT,
(ProjectWebOutput { handle, event },),
)
.await
{
Ok(projected) => projected,
Err(error) => {
log::warn!(
"[web-channel] output event not projected request_id={}: {error}",
self.ids.request_id
);
return;
}
};
let terminal = projected.events.iter().any(is_terminal);
for mut event in projected.events {
if !self.sequenced {
event.context_mut().seq = None;
}
self.publish(event, interim_round, true);
}
if terminal {
self.end_if_needed(&mut state).await;
}
}
/// The leading narration of `round`, flushed as an interim bubble.
pub(crate) async fn interim(&self, round: u32, text: String) {
self.project(
ChannelOutputEvent::Clarification { prompt: text },
Some(round),
)
.await;
}
/// Publish a host-authored event unchanged (queue, goal, todo, or the
/// enriched terminal event). It has no canonical projection form, but it
/// still closes any module-owned projection state for the turn.
pub(crate) async fn event(&self, event: bus_web::WebChannelEvent) {
let terminal = matches!(
&event,
bus_web::WebChannelEvent::ChatDone { .. }
| bus_web::WebChannelEvent::ChatError { .. }
| bus_web::WebChannelEvent::ChatCancelled { .. }
);
let mut state = self.state.lock().await;
self.publish(event, None, false);
if terminal {
self.end_if_needed(&mut state).await;
}
}
/// The addressing context for an event of this turn.
pub(crate) fn context(&self) -> bus_web::WebEventContext {
bus_web::WebEventContext {
client_id: self.ids.client_id.clone(),
thread_id: self.ids.thread_id.clone(),
request_id: self.ids.request_id.clone(),
..Default::default()
}
}
}
impl Drop for SurfaceState {
fn drop(&mut self) {
let Some(handle) = self.handle.take() else {
self.cleanup_done.notify_one();
return;
};
let Some(module) = self.module.as_ref().cloned() else {
self.cleanup_done.notify_one();
return;
};
let Some(runtime) = self.cleanup_runtime.as_ref() else {
log::warn!(
"[web-channel] dropped projection turn without a cleanup runtime request_id={}",
self.request_id
);
return;
};
let runtime = runtime.clone();
let cleanup_done = Arc::clone(&self.cleanup_done);
let request_id = self.request_id.clone();
runtime.spawn(async move {
if let Err(error) = module
.call_confidential::<()>(
"tinychannels",
tinychannels_bus::methods::END_WEB_TURN,
(EndWebTurn {
handle: handle.handle,
},),
)
.await
{
log::warn!(
"[web-channel] dropped projection turn cleanup failed request_id={request_id}: {error}"
);
}
cleanup_done.notify_one();
});
}
}
fn is_terminal(event: &bus_web::WebChannelEvent) -> bool {
matches!(
event,
bus_web::WebChannelEvent::ChatDone { .. }
| bus_web::WebChannelEvent::ChatError { .. }
| bus_web::WebChannelEvent::ChatCancelled { .. }
)
}
#[cfg(test)]
#[path = "surface_tests.rs"]
mod tests;