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
//! Reaching the `tinyconnectors` module.
//!
//! The connector implementation — the Composio client, the OAuth handoff, the
//! execute pipeline, the trigger archive, the sync providers — lives in the
//! `tinyconnectors` module, not in this crate. This is how the host calls it.
//!
//! # What stays here
//!
//! Three things deliberately did not move, and callers must keep applying them
//! around these calls:
//!
//! - **Egress policy.** [`crate::security::egress`] refuses outbound
//! tool calls under local-only mode and discloses every external transfer.
//! That is host policy about the *user's* data, and the module cannot see the
//! reasons behind it. Apply it before calling [`methods::EXECUTE`].
//! - **Which route to use.** Whether the user is signed in, whether they
//! supplied their own Composio key, and which the product prefers are all
//! decisions this crate makes. They become the module's configuration blob,
//! and the module honours it rather than choosing.
//! - **Webhook delivery.** The backend HMAC-verifies Composio webhooks and fans
//! them out over the user's sockets. The module has no socket, so the
//! existing trigger subscriber keeps its job.
//!
//! # What the module now owns
//!
//! Scope enforcement. `ListTools` hides what the user's preference forbids and
//! `Execute` refuses it. Do **not** re-filter here against a separately stored
//! preference: two sources of truth for a permission is how one of them ends up
//! stale and permissive.
use std::sync::{Arc, Mutex};
use serde::de::DeserializeOwned;
use serde::Serialize;
use tinybus::Proxy;
use tinyconnectors_bus::names;
use super::types::ModuleState;
use super::{ops, registry};
use crate::config::schema::{COMPOSIO_MODE_BACKEND, COMPOSIO_MODE_DIRECT};
use crate::config::Config;
use crate::core::slots::HookSlot;
/// The module's id in [`registry`].
pub const MODULE_ID: &str = "tinyconnectors";
/// The names of the members this host calls.
///
/// Re-exported so a call site spells a member through the contract rather than
/// as a string literal: a renamed member is then a compile error here instead
/// of an "unknown method" at runtime on a user's machine.
pub use names::methods;
/// Where the connector module's proxy route sends its requests: the origin and
/// the bearer secret it authenticates with.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ProxyTarget {
/// The origin the proxy route is joined onto.
pub base_url: String,
/// The bearer secret (a session token or an API key).
pub auth_token: String,
}
/// Resolves the [`ProxyTarget`] for one `composio.mode`, or the user-facing
/// reason there is none (not signed in, no credential).
pub type ProxyTargetResolver = Arc<dyn Fn(&Config) -> Result<ProxyTarget, String> + Send + Sync>;
static MODULE_PROXY_TARGETS: HookSlot<ProxyTargetResolver> =
HookSlot::new("modules::connectors::proxy_targets");
#[path = "connectors/inspection.rs"]
mod inspection;
pub(crate) use inspection::{call_existing_readonly, ExistingCallError};
pub(crate) fn note_module_config_for_load(config: &Config, module_config: &serde_json::Value) {
inspection::note_module_config_for_load(config, module_config);
}
pub(crate) fn note_load_resolution_ready() {
inspection::note_load_resolution_ready();
}
/// Registers `resolve` as the proxy target for `mode` (`"backend"` is the one
/// mode the proxy route serves). Nothing registered => the mode has no route.
pub fn register_proxy_target<F>(mode: impl Into<String>, resolve: F)
where
F: Fn(&Config) -> Result<ProxyTarget, String> + Send + Sync + 'static,
{
MODULE_PROXY_TARGETS.register(mode, Arc::new(resolve));
}
/// Removes the process-wide proxy target for `mode`.
pub fn unregister_proxy_target(mode: &str) -> bool {
MODULE_PROXY_TARGETS.unregister(mode)
}
/// The configuration blob the module is loaded with.
///
/// This is where "which route" is decided, and it is the whole of the host's
/// say in the matter: the module implements both routes and chooses neither.
/// Everything it needs to reach Composio arrives here, and it reads a
/// credential from nowhere else.
///
/// # Errors
///
/// Returns a message when the configured mode cannot be honoured — direct mode
/// with no key, or a mode string that is neither. A typo in `config.toml` fails
/// loudly rather than silently downgrading to the other route, which would send
/// a user's requests somewhere they did not choose.
pub fn module_config(config: &Config) -> Result<serde_json::Value, String> {
module_config_with_proxy(config, &crate::config::runtime_proxy_config())
}
/// [`module_config`] against an explicit proxy policy rather than the
/// process-global runtime one.
pub(crate) fn module_config_with_proxy(
config: &Config,
proxy: &crate::config::schema::ProxyConfig,
) -> Result<serde_json::Value, String> {
let mut payload = route_config(config, proxy)?;
payload["offered_toolkits"] = offered_toolkits(config);
Ok(payload)
}
/// The host's offered-toolkit policy as the module reads it
/// (`tinyconnectors_bus::vocabulary::OfferedToolkits`). Also the whole load
/// blob when no route can be named, so the policy still applies to the
/// capability listings of a signed-out module.
#[must_use]
pub fn offered_toolkits(config: &Config) -> serde_json::Value {
serde_json::json!({
"allow": config.composio.offered_toolkits_allow,
"deny": config.composio.offered_toolkits_deny,
})
}
fn route_config(
config: &Config,
proxy: &crate::config::schema::ProxyConfig,
) -> Result<serde_json::Value, String> {
let state_dir = config.workspace_dir.join("state");
// A host-pinned credential outranks the mode and the credential store, the
// way `resolve_composio_route` resolves it, so the module's configured route
// (executes, the connected-integrations overview) is the pinned tenant too.
if let Some(pinned) = config.composio.host_credential.as_ref() {
let base = pinned.direct_base_urls().map(|urls| urls.v3.clone());
let destination = base
.as_deref()
.unwrap_or("https://backend.composio.dev/api/v3");
let mut payload = serde_json::json!({
"route": "direct",
"api_key": pinned.api_key(),
"entity_id": pinned.entity(),
"base_url": base,
"state_dir": state_dir,
});
if let Some(transport) =
crate::integrations::composio::client::module_transport_with_proxy(destination, proxy)
{
payload["transport"] = serde_json::json!(transport);
}
return Ok(payload);
}
match config.composio.mode.trim() {
// Empty is the default, for hand-edited configs that omit the field.
"" | COMPOSIO_MODE_BACKEND => {
let target = MODULE_PROXY_TARGETS
.get(COMPOSIO_MODE_BACKEND)
.ok_or_else(|| {
format!(
"{}composio backend mode is not available in this build",
crate::core::observability::BACKEND_UNAVAILABLE_PREFIX
)
})
.and_then(|resolve| resolve(config))?;
// The backend renders Composio results (Gmail timestamps) for the
// model; with the user's zone it prints local time beside UTC. A
// module before contract 1.9 ignores the field. It is part of the
// route fingerprint, so a zone change reconfigures on the next call.
let timezone =
crate::integrations::composio::googlecalendar_args::current_iana_timezone();
Ok(serde_json::json!({
"route": "proxy",
"base_url": target.base_url,
// The session JWT or the TinyHumans API key. The proxy route
// sends it as `Authorization: Bearer`; the backend recognises
// a key there by its `tiny_` prefix, so no scheme flag is needed.
"auth_token": target.auth_token,
"timezone": timezone,
"state_dir": state_dir,
}))
}
COMPOSIO_MODE_DIRECT => {
// The keychain wins over `config.toml`: the encrypted store is the
// source of truth, and the file is a fallback for power users.
let stored = crate::security::credentials::get_composio_api_key(config)
.map_err(|error| format!("failed to read the stored composio api key: {error}"))?;
let api_key = stored
.or_else(|| {
config
.composio
.api_key
.as_ref()
.map(|key| key.trim().to_string())
.filter(|key| !key.is_empty())
})
.ok_or_else(|| {
"composio direct mode is selected but no api key is configured (set it via \
composio.set_api_key or config.composio.api_key)"
.to_string()
})?;
// The module accepts an optional base override and defaults to the
// real Composio API without one. Before the extraction the host's
// direct scan honoured OPENHUMAN_COMPOSIO_DIRECT_BASE_V3 (and V2)
// — test rigs and proxies point Composio at a loopback mock with
// it — and omitting the field here silently killed that contract:
// the module dialled backend.composio.dev regardless. Forward it.
// The module's transport still refuses any non-HTTPS, non-loopback
// base, so this cannot redirect a real credential to plain HTTP.
let direct_base = std::env::var("OPENHUMAN_COMPOSIO_DIRECT_BASE_V3")
.or_else(|_| std::env::var("OPENHUMAN_COMPOSIO_DIRECT_BASE_V2"))
.ok()
.map(|base| base.trim().to_string())
.filter(|base| !base.is_empty());
let mut payload = serde_json::json!({
"route": "direct",
"api_key": api_key,
"entity_id": config.composio.entity_id,
"base_url": std::env::var("OPENHUMAN_COMPOSIO_DIRECT_BASE_V3").ok(),
"state_dir": state_dir,
});
if let Some(base) = &direct_base {
payload["base_url"] = serde_json::Value::String(base.clone());
}
// The host's proxy and TLS policy for Composio, resolved for the
// destination the module will dial. Part of the route description,
// so a change in the proxy settings reconfigures the module on the
// next call. Omitted when it is the module's default (contract 1.10).
let destination = direct_base
.as_deref()
.unwrap_or("https://backend.composio.dev/api/v3");
if let Some(transport) =
crate::integrations::composio::client::module_transport_with_proxy(
destination,
proxy,
)
{
payload["transport"] = serde_json::json!(transport);
}
Ok(payload)
}
unknown => Err(format!(
"unknown composio mode: \"{unknown}\". Supported: \"{COMPOSIO_MODE_BACKEND}\", \
\"{COMPOSIO_MODE_DIRECT}\""
)),
}
}
/// Read the connector module's curated catalogs into the host's snapshot.
///
/// Called once the module is serving (see `ops::start_resolution`) and at
/// boot when it was already serving from the search path. A failure only
/// delays the snapshot: the next connector call primes it again.
pub async fn prime_catalogs(config: &Config) {
if let Err(error) = crate::integrations::composio::contract::curated::prime(config).await {
tracing::debug!("[connectors] catalog prime failed: {error}");
}
}
/// The route description last sent to the module, as a fingerprint.
///
/// Only a hash is kept: comparing routes means comparing bearer tokens, and a
/// process-lifetime static holding one in cleartext is a credential sitting
/// somewhere nothing needs it.
fn last_route() -> &'static Mutex<Option<u64>> {
static LAST: std::sync::OnceLock<Mutex<Option<u64>>> = std::sync::OnceLock::new();
LAST.get_or_init(|| Mutex::new(None))
}
/// Hash a route description so it can be compared without being stored.
fn fingerprint(route: &serde_json::Value) -> u64 {
use std::hash::{Hash, Hasher};
let mut hasher = std::collections::hash_map::DefaultHasher::new();
route.to_string().hash(&mut hasher);
hasher.finish()
}
/// Under test, one route-dependent call at a time.
///
/// The module's route is process-global, and every call first sets it from its
/// own caller's config (`ensure_routed`). libtest runs a crate's tests in one
/// process, so a test with no session could switch the route to `none` between
/// another test's CONFIGURE and its call. Holding this across both makes each
/// call atomic with its route. ponytail: test-only; production callers with
/// different routes can still interleave the same way, which this does not fix.
#[cfg(test)]
static ROUTE_TURN: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());
/// Tell the module which route to use, if that answer has changed.
///
/// The module is registered `Lazy`, so it is commonly loaded the first time
/// anything touches a connector — which for most sessions is *before* the user
/// signs in. Its load-time configuration would then be routeless, and a module
/// that only took a route at load would leave that user unable to reach
/// Composio until they restarted the application. Sign-out is the same problem
/// reversed: the module would keep a bearer that now answers 401 to everything.
///
/// So the route is reconciled on every call rather than only at load. In steady
/// state that is a hash and a comparison; a bus round-trip happens only when the
/// answer actually changed.
///
/// A config that cannot name a route — signed out, direct mode with no key —
/// sends `{"route": "none"}` rather than nothing. Leaving the old route in
/// place would have the module answering 401 to everything with a bearer the
/// user's session no longer owns, and "your account is broken" is a bad way to
/// tell someone they are signed out.
async fn ensure_routed(config: &Config, proxy: &Proxy) -> Result<(), String> {
let _inspection_guard = inspection::route_lock().lock().await;
let mut route =
module_config(config).unwrap_or_else(|_| serde_json::json!({ "route": "none" }));
// `state_dir` is load-time only: the trigger archive opens once, and moving
// it later would strand the history already written there.
if let Some(object) = route.as_object_mut() {
object.remove("state_dir");
// Load-time like `state_dir`: the policy is not part of the route.
object.remove("offered_toolkits");
}
// Preferences and trigger history from before the storage contract move
// into the module's storage before it first serves a call. Once per state
// directory, best effort: a failure is retried on the next call.
super::import_legacy_connectors(
&crate::core::runtime::DispatchCtx::ambient(),
&config.workspace_dir.join("state"),
)
.await;
let current = fingerprint(&route);
if *last_route()
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
== Some(current)
{
return Ok(());
}
let inspection_binding = inspection::configured_binding_for_route(config, &route);
proxy
.call_confidential::<serde_json::Value>(methods::CONFIGURE, (route,))
.await
.map_err(|error| bus_failure(methods::CONFIGURE, &error))?;
// Recorded only after the module accepted it, so a failed reconfiguration
// is retried on the next call rather than remembered as done.
*last_route()
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner) = Some(current);
inspection::record_configured_route(inspection_binding);
Ok(())
}
/// A proxy to the connector module, loading it if this is the first call.
///
/// The module is registered `Lazy`, so this is where a user with connected
/// accounts pays to load it and a user without one never does.
///
/// # Errors
///
/// Returns a message naming what went wrong: modules disabled in configuration,
/// the artifact missing or failing its digest check, or the bus refusing the
/// proxy.
pub async fn proxy(config: &Config) -> Result<Proxy, String> {
ops::ensure_loaded(config, MODULE_ID)
.await
.map_err(|_| tinybus::module::ModuleCallError::Unavailable.to_string())?;
let proxy = proxy_to_serving().await?;
ensure_routed(config, &proxy).await?;
Ok(proxy)
}
/// A proxy to the module as it is serving right now — no load, no route
/// reconciliation. Callers decide which of those they need.
async fn proxy_to_serving() -> Result<Proxy, String> {
let record =
registry::find(MODULE_ID).ok_or_else(|| format!("unknown module '{MODULE_ID}'"))?;
let runtime = super::runtime::runtime().await.map_err(|_| {
super::report::transport_failed(record);
tinybus::module::ModuleCallError::TransportFailed.to_string()
})?;
runtime
.proxy(record.bus_name, record.object_path)
.map_err(|error| bus_failure("Connect", &error))
}
/// Give an already-serving module the route the current configuration
/// selects, without loading a module that is not serving.
///
/// Every call reconciles the route (`ensure_routed`), and that is how sign-out
/// reaches a module configured while the user was signed in: the next call
/// sends `{"route": "none"}` and the module drops the bearer. A caller that
/// answers a signed-out user itself — `composio_list_connections`, which the
/// periodic sync drives every minute — makes no such call, so it uses this to
/// give the instruction anyway; otherwise the credential would stay resident
/// until some other member happened to be used. A module that was never
/// loaded holds no credential, and boot is the wrong moment to download one,
/// so a module that is not serving is left alone.
///
/// # Errors
///
/// Returns a message when the module is serving but could not be reached or
/// refused the reconfiguration. Nothing is recorded in that case, so the next
/// call retries.
pub async fn reconcile_route_if_loaded(config: &Config) -> Result<(), String> {
if ops::state_of(MODULE_ID) != ModuleState::Ready {
return Ok(());
}
#[cfg(test)]
let _turn = ROUTE_TURN.lock().await;
let proxy = proxy_to_serving().await?;
ensure_routed(config, &proxy).await
}
/// Whether the route the module last accepted is the signed-out one.
#[cfg(test)]
pub(crate) fn last_route_is_none() -> bool {
*last_route()
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner)
== Some(fingerprint(&serde_json::json!({ "route": "none" })))
}
/// A proxy to the serving module that does NOT reconcile the route first —
/// for tests that need to observe what the module currently holds.
#[cfg(test)]
pub(crate) async fn proxy_without_reconcile() -> Result<Proxy, String> {
proxy_to_serving().await
}
fn bus_failure(member: &str, error: &tinybus::Error) -> String {
let outcome = super::report::proxy_failure(
registry::find(MODULE_ID).expect("registered connector module"),
error,
);
if let tinybus::Error::MethodFailed { name, message } = error {
if message.starts_with("[composio:error:") {
// Preserve the existing provider presentation contract. This is
// product output only; telemetry above contains no remote text.
return message.clone();
}
if name == tinybus::Error::FAILED {
// Keep provider presentation byte-for-byte. The Composio reporting
// boundary recognizes this wire envelope without a visible marker.
return format!("{member}: {error}");
}
}
format!("{member}: {outcome}")
}
/// Call one member with an argument and decode its reply.
///
/// # Errors
///
/// Returns the member's failure as the module rendered it.
///
/// Note what is *not* an error: a Composio action the provider refused comes
/// back as a successful reply carrying `successful: false` and a formatted
/// message. A caller that checks only for `Err` here will report a failed send
/// as a success.
pub async fn call<Request, Reply>(
config: &Config,
member: &str,
request: Request,
) -> Result<Reply, String>
where
Request: Serialize + Send,
Reply: DeserializeOwned,
{
#[cfg(test)]
let _turn = ROUTE_TURN.lock().await;
let proxy = proxy(config).await?;
proxy
.call::<Reply>(member, (request,))
.await
.map_err(|error| bus_failure(member, &error))
}
/// Call a member that carries its own credential, without touching the route.
///
/// `ListConnectionsDirect` and `ListToolsDirect` read as the credential on the
/// request, so the module's configured route is neither used nor replaced. That
/// is why this does not reconcile the route first: a host serving several
/// credentials from one module must not have one caller's configuration
/// overwrite another's mid-call, and a config that names no route here would
/// otherwise send the module `{"route": "none"}` in the middle of a read.
///
/// # Errors
///
/// As [`call`].
pub async fn call_stateless<Request, Reply>(
config: &Config,
member: &str,
request: Request,
) -> Result<Reply, String>
where
Request: Serialize + Send,
Reply: DeserializeOwned,
{
// The module's own HTTP deadline is 30s; give the bus a little longer so a
// slow Composio surfaces as the module's message, not a bus timeout.
const STATELESS_TIMEOUT: std::time::Duration = std::time::Duration::from_secs(45);
ops::ensure_loaded(config, MODULE_ID)
.await
.map_err(|_| tinybus::module::ModuleCallError::Unavailable.to_string())?;
let proxy = proxy_to_serving().await?.with_timeout(STATELESS_TIMEOUT);
proxy
.call_confidential::<Reply>(member, (request,))
.await
.map_err(|error| bus_failure(member, &error))
}
/// Call a member that takes no arguments.
///
/// # Errors
///
/// As [`call`].
pub async fn call_bare<Reply: DeserializeOwned>(
config: &Config,
member: &str,
) -> Result<Reply, String> {
#[cfg(test)]
let _turn = ROUTE_TURN.lock().await;
let proxy = proxy(config).await?;
proxy
.call::<Reply>(member, ())
.await
.map_err(|error| bus_failure(member, &error))
}
#[cfg(test)]
#[path = "connectors_tests.rs"]
mod tests;