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
//! `show_ui`: lets a skill render its own HTML in the chat, in the same
//! sandboxed frame MCP widgets use.
//!
//! The document comes inline or from an `.html` file confined to the action
//! directory, the workspace, or the user's skill bundles. The frame it runs in
//! cannot call tools; it can only ask the host to open a link or prefill the
//! composer.
use std::path::{Component, Path, PathBuf};
use async_trait::async_trait;
use serde_json::{json, Value};
use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolExposure, ToolResult, ToolRunContext};
use super::cache::{self, InlineEntry};
use super::resolve::{MAX_RESOURCE_BYTES, MAX_STRUCTURED_BYTES};
use super::types::{McpUiPresentation, UiCsp, UiFlavor, UiResource, MCP_APP_MIME, MCP_UI_KIND};
use tinymcp_bus::ui::extract_links;
/// The tool's registered name.
pub const SHOW_UI_TOOL: &str = "show_ui";
const MAX_TITLE_CHARS: usize = 80;
/// The `show_ui` tool.
pub struct ShowUiTool {
roots: Vec<PathBuf>,
}
impl ShowUiTool {
/// A tool reading files under `roots` only.
#[must_use]
pub fn new(roots: Vec<PathBuf>) -> Self {
Self { roots }
}
/// The tool for `config`: the action directory, the workspace and the
/// user's skill bundles.
#[must_use]
pub fn for_config(config: &crate::config::Config) -> Self {
let mut roots = vec![config.action_dir.clone(), config.workspace_dir.clone()];
#[cfg(feature = "skills")]
{
if let Some(home) = crate::skills::ops_discover::discovery_home_dir() {
roots.push(home.join(".openhuman").join("skills"));
}
}
#[cfg(not(feature = "skills"))]
let _ = &mut roots;
Self::new(roots)
}
}
/// `path` resolved inside one of `roots`, refusing traversal, symlink escapes
/// and anything but `.html` / `.htm`.
///
/// # Errors
///
/// When the path is malformed, outside every root, or not an HTML file.
pub fn confine_path(roots: &[PathBuf], path: &str) -> Result<PathBuf, String> {
confine_path_in(roots, path).map(|(_, resolved)| resolved)
}
/// [`confine_path`], also returning the canonical root that contains the file.
///
/// # Errors
///
/// As [`confine_path`].
pub fn confine_path_in(roots: &[PathBuf], path: &str) -> Result<(PathBuf, PathBuf), String> {
let requested = Path::new(path.trim());
if path.trim().is_empty() || path.contains('\0') {
return Err("path must not be empty".to_string());
}
if requested
.components()
.any(|component| matches!(component, Component::ParentDir))
{
return Err("path must not contain `..`".to_string());
}
let extension = requested
.extension()
.and_then(|ext| ext.to_str())
.map(str::to_ascii_lowercase);
if !matches!(extension.as_deref(), Some("html" | "htm")) {
return Err("only .html files can be shown".to_string());
}
for root in roots {
let Ok(canonical_root) = root.canonicalize() else {
continue;
};
let candidate = if requested.is_absolute() {
requested.to_path_buf()
} else {
canonical_root.join(requested)
};
let Ok(resolved) = candidate.canonicalize() else {
continue;
};
if resolved.starts_with(&canonical_root) && resolved.is_file() {
return Ok((canonical_root, resolved));
}
}
Err("the file is not inside the workspace or a skill bundle".to_string())
}
/// Reads `resolved` through one handle opened without following links below
/// `root`, bounded by [`MAX_RESOURCE_BYTES`].
///
/// # Errors
///
/// When the open is refused, the file is not regular, or it is too large.
pub async fn read_confined(
ctx: &crate::core::runtime::DispatchCtx,
root: PathBuf,
resolved: PathBuf,
) -> Result<String, String> {
ctx.spawn_blocking(move || {
use std::io::Read;
let file =
crate::security::secure_open::secure_open(&resolved, &root).map_err(|error| {
tracing::debug!(?error, "[mcp_ui] show_ui refused the file open");
"the file is not inside the workspace or a skill bundle".to_string()
})?;
let metadata = file
.metadata()
.map_err(|_| "could not read the file".to_string())?;
if !metadata.is_file() {
return Err("only regular files can be shown".to_string());
}
if metadata.len() > MAX_RESOURCE_BYTES as u64 {
return Err("the file is too large to show".to_string());
}
let mut html = String::new();
file.take(MAX_RESOURCE_BYTES as u64 + 1)
.read_to_string(&mut html)
.map_err(|_| "could not read the file".to_string())?;
if html.len() > MAX_RESOURCE_BYTES {
return Err("the file is too large to show".to_string());
}
Ok(html)
})
.await
.map_err(|_| "could not read the file".to_string())?
}
fn clean_title(raw: Option<&str>) -> Option<String> {
let title: String = raw?
.chars()
.filter(|c| !c.is_control())
.take(MAX_TITLE_CHARS)
.collect();
let title = title.trim().to_string();
(!title.is_empty()).then_some(title)
}
#[async_trait]
impl Tool for ShowUiTool {
fn name(&self) -> &str {
SHOW_UI_TOOL
}
fn description(&self) -> &str {
"Show an interactive HTML view inline in the chat, in a sandbox. Pass `html`, or `path` to an .html file in the workspace or a skill bundle, plus an optional `title` and a `data` object the page receives as its tool result. The page cannot call tools or reach the network; use it for visual output a skill produces."
}
fn parameters_schema(&self) -> Value {
json!({
"type": "object",
"properties": {
"html": {"type": "string", "description": "A complete HTML document."},
"path": {"type": "string", "description": "An .html file in the workspace or a skill bundle."},
"title": {"type": "string", "description": "A short label for the view."},
"data": {"type": "object", "description": "Data handed to the page."}
}
})
}
fn permission_level(&self) -> PermissionLevel {
PermissionLevel::ReadOnly
}
fn exposure(&self) -> ToolExposure {
ToolExposure::Deferred
}
async fn execute(&self, args: Value) -> anyhow::Result<ToolResult> {
self.execute_with_context(args, ToolCallOptions::default(), None)
.await
}
async fn execute_with_context(
&self,
args: Value,
_options: ToolCallOptions,
tool_context: Option<&dyn ToolRunContext>,
) -> anyhow::Result<ToolResult> {
let ctx = crate::agent::tinyagents::host::run_context::dispatch_ctx_for_tool(tool_context);
let html_arg = args.get("html").and_then(Value::as_str);
let path_arg = args.get("path").and_then(Value::as_str);
let html = match (html_arg, path_arg) {
(Some(html), None) => html.to_string(),
(None, Some(path)) => {
let (root, resolved) = match confine_path_in(&self.roots, path) {
Ok(found) => found,
Err(error) => return Ok(ToolResult::error(format!("show_ui: {error}"))),
};
match read_confined(&ctx, root, resolved).await {
Ok(html) => html,
Err(error) => return Ok(ToolResult::error(format!("show_ui: {error}"))),
}
}
_ => {
return Ok(ToolResult::error(
"show_ui: pass exactly one of `html` or `path`",
));
}
};
if html.trim().is_empty() {
return Ok(ToolResult::error("show_ui: the document is empty"));
}
if html.len() > MAX_RESOURCE_BYTES {
return Ok(ToolResult::error(
"show_ui: the document is too large to show",
));
}
let data = args
.get("data")
.filter(|value| value.is_object())
.filter(|value| {
serde_json::to_vec(value)
.map(|bytes| bytes.len() <= MAX_STRUCTURED_BYTES)
.unwrap_or(false)
})
.cloned();
let title = clean_title(args.get("title").and_then(Value::as_str));
let inline_id = cache::put_inline(InlineEntry {
server_id: None,
resource: UiResource {
html,
mime_type: MCP_APP_MIME.to_string(),
csp: UiCsp::default(),
permissions: None,
prefers_border: true,
},
});
let presentation = McpUiPresentation {
kind: MCP_UI_KIND.to_string(),
flavor: UiFlavor::HostInline,
server_id: None,
tool: SHOW_UI_TOOL.to_string(),
resource_uri: None,
inline_id: Some(inline_id),
title: title.clone(),
tool_input: data.clone().unwrap_or(Value::Null),
structured_content: data.clone(),
result_meta: None,
links: extract_links(data.as_ref(), ""),
};
tracing::debug!(title = ?title, "[mcp_ui] show_ui rendered a host view");
let mut result = ToolResult::success(match &title {
Some(title) => format!("Shown \"{title}\" inline in the chat."),
None => "Shown the view inline in the chat.".to_string(),
});
result.metadata = Some(presentation.to_metadata());
Ok(result)
}
}
#[cfg(test)]
#[path = "tools_tests.rs"]
mod tests;