Skip to content

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

22.4 KB
Raw Blame
//! 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;