Skip to content

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

14.1 KB
Raw Blame
//! Calling the connector module, or explaining why it is not there.
//!
//! Every Composio operation now lives in the `tinyconnectors` module, which is
//! loaded through [`crate::modules`] — and that is behind the
//! `modules` feature. A build with gates off has no loader, so it has no
//! connectors either.
//!
//! The `#[cfg]` lives here rather than on each handler. Twelve handlers with a
//! feature gate each is twelve chances to gate one of them differently, and the
//! gates-off build only fails on whichever is compiled first. One switch, one
//! message, and the handlers read the same either way.
//!
//! # What the member names do *not* depend on
//!
//! The method constants come from `tinyconnectors_bus`, an ordinary dependency with no
//! feature gate. A gates-off build can still name a member and match on the
//! contract; it just cannot call one.

/// Whether a member failure is the module refusing an operation the live route
/// does not offer.
///
/// The two routes are not equivalent — direct mode has no per-user toolkit
/// allowlist, and no webhook endpoint for triggers — and the module says so by
/// name rather than by returning an empty result. A caller that wants to render
/// its own answer for that case has to tell the refusal apart from a real
/// failure, and getting it backwards would show "no curated allowlist" over an
/// outage, leaving the user unaware their integration had broken.
///
/// Matched on the message because that is what crosses the bus: `TinyBus`
/// carries an error name and a string, so the structure of the module's error
/// is flattened by the time it arrives.
#[must_use]
pub fn is_unsupported_by_route(error: &str) -> bool {
    error.contains("is not available over the") && error.contains("route")
}

/// Keep the structured Composio classification at the start of the error.
///
/// TinyBus prefixes a member failure with the member name (`Execute: `) and,
/// since the module extraction, with its wire error name
/// (`ai.tinyhumans.tinybus.Error.<Kind>: `) — but the frontend parser
/// intentionally requires the classification at byte zero, so every transport
/// layer is peeled before checking. Errors that are not classified retain their
/// full context unchanged.
///
/// # Why the wire layer is peeled in a loop
///
/// It used to be peeled once, with a second `strip_prefix` afterwards as a
/// fallback for `Error.Failed: ` specifically. That fallback could not fire for
/// the shape its comment described: the single peel above it already consumed
/// `Error.Failed: `, so the branch was reachable only by a *doubly* wire-wrapped
/// error — which nothing documented, and which the fallback's own comment did
/// not claim to handle. Nesting depth is a property of the transport, not
/// something this function should hardcode a guess at, so it now strips as many
/// layers as are present. Output is unchanged for every shape the old form
/// handled, including the double wrap the fallback did catch; a triple or deeper
/// wrap, which the old form silently passed through unnormalised (and so
/// reported to the user as an unclassified outage), now normalises too.
fn normalize_error(member: &str, error: String) -> String {
    const CLASSIFIED: &str = "[composio:error:";
    const WIRE_ERROR_PREFIX: &str = "ai.tinyhumans.tinybus.Error.";
    if let Some(remainder) = error
        .strip_prefix(member)
        .and_then(|remainder| remainder.strip_prefix(": "))
    {
        // Peel each `ai.tinyhumans.tinybus.Error.<Kind>: ` layer. `<Kind>` is a
        // bare identifier, so the next `: ` ends it; anything shaped differently
        // stops the loop and is left alone. An embedded marker that does NOT
        // follow a wire prefix is never promoted — the `starts_with` below is
        // what decides, and it runs on the fully-peeled remainder only.
        let mut module_error = remainder;
        while let Some(tail) = module_error
            .strip_prefix(WIRE_ERROR_PREFIX)
            .and_then(|rest| rest.split_once(": ").map(|(_, tail)| tail))
        {
            module_error = tail;
        }
        if module_error.starts_with(CLASSIFIED) {
            return module_error.to_string();
        }
    }
    error
}

/// The message a gates-off build answers every connector call with.
#[cfg(not(feature = "modules"))]
const WITHOUT_MODULES: &str =
    "composio is unavailable in this build: connectors run in the `tinyconnectors` module, \
     which needs the `modules` feature";

/// Fill the process snapshot of the module's curated catalogs, once per
/// pinned module version. The synchronous catalog lookups read that snapshot,
/// so it must exist before the first call whose reply they gate. A failure is
/// logged and the call proceeds: the lookups then read every toolkit as
/// uncurated until a later call succeeds.
#[cfg(feature = "modules")]
async fn prime_curated_catalogs(config: &crate::config::Config) {
    if let Err(error) = super::contract::curated::prime(config).await {
        tracing::debug!("[composio][curated] prime failed: {error}");
    }
}

/// Make sure the curated-catalog snapshot is filled before a lookup that does
/// not itself call the module (the agent-ready list, catalog search). The
/// module is loaded if it is not yet, then asked once per pinned version.
///
/// # Errors
///
/// The module could not be reached, so the snapshot is empty and an answer read
/// from it would look like "no curated toolkits" rather than "unknown". A build
/// without a module loader has no catalogs to read and answers `Ok`.
#[cfg(feature = "modules")]
pub async fn ensure_catalogs(config: &crate::config::Config) -> Result<(), String> {
    super::contract::curated::prime(config)
        .await
        .map_err(|error| {
            tracing::debug!("[composio][curated] prime failed: {error}");
            error
        })
}

/// Without the module loader there is no catalog to read.
#[cfg(not(feature = "modules"))]
pub async fn ensure_catalogs(_config: &crate::config::Config) -> Result<(), String> {
    Ok(())
}

/// Call one member with an argument and decode its reply.
///
/// # Errors
///
/// Returns the member's failure as the module rendered it, or an explanation
/// when this build has no module loader.
///
/// Note what is *not* an error: a Composio action the provider refused comes
/// back as a successful reply carrying `successful: false`. A caller that
/// checks only for `Err` will report a failed send as a success.
#[cfg(feature = "modules")]
pub async fn call<Request, Reply>(
    config: &crate::config::Config,
    member: &str,
    request: Request,
) -> Result<Reply, String>
where
    Request: serde::Serialize + Send,
    Reply: serde::de::DeserializeOwned,
{
    prime_curated_catalogs(config).await;
    crate::modules::connectors::call(config, member, request)
        .await
        .map_err(|error| normalize_error(member, error))
}

/// Call one member with an argument. Always fails without the `modules` feature.
///
/// # Errors
///
/// Always, explaining that this build has no module loader.
#[cfg(not(feature = "modules"))]
pub async fn call<Request, Reply>(
    _config: &crate::config::Config,
    member: &str,
    _request: Request,
) -> Result<Reply, String>
where
    Request: serde::Serialize + Send,
    Reply: serde::de::DeserializeOwned,
{
    crate::modules::client(_config.clone())
        .call::<Reply>("tinyconnectors", member, (_request,))
        .await
        .map_err(|error| format!("{member}: {error}; {WITHOUT_MODULES}"))
}

/// Give an already-serving connector module the route the current config
/// selects — for a signed-out user, that means dropping the credential it was
/// configured with while signed in — without loading a module that is not
/// serving. See `modules::connectors::reconcile_route_if_loaded`.
///
/// # Errors
///
/// As the module function: the module is serving but could not be reached or
/// refused the reconfiguration.
#[cfg(feature = "modules")]
pub async fn reconcile_route_if_loaded(config: &crate::config::Config) -> Result<(), String> {
    crate::modules::connectors::reconcile_route_if_loaded(config).await
}

/// Without the module loader there is no module holding a route. Always `Ok`.
#[cfg(not(feature = "modules"))]
pub async fn reconcile_route_if_loaded(_config: &crate::config::Config) -> Result<(), String> {
    Ok(())
}

/// Call a member that carries its own credential and leaves the configured
/// route alone (the stateless direct reads).
///
/// # Errors
///
/// As [`call`].
#[cfg(feature = "modules")]
pub async fn call_stateless<Request, Reply>(
    config: &crate::config::Config,
    member: &str,
    request: Request,
) -> Result<Reply, String>
where
    Request: serde::Serialize + Send,
    Reply: serde::de::DeserializeOwned,
{
    prime_curated_catalogs(config).await;
    crate::modules::connectors::call_stateless(config, member, request).await
}

/// Call a stateless member. Always fails without the `modules` feature.
///
/// # Errors
///
/// Always, explaining that this build has no module loader.
#[cfg(not(feature = "modules"))]
pub async fn call_stateless<Request, Reply>(
    _config: &crate::config::Config,
    member: &str,
    _request: Request,
) -> Result<Reply, String>
where
    Request: serde::Serialize + Send,
    Reply: serde::de::DeserializeOwned,
{
    crate::modules::client(_config.clone())
        .call::<Reply>("tinyconnectors", member, (_request,))
        .await
        .map_err(|error| format!("{member}: {error}; {WITHOUT_MODULES}"))
}

/// The message a stateless member's failure carries, with the transport layers
/// peeled off.
///
/// The bus renders a member failure as `<Member>: ai.tinyhumans.tinybus.Error.<Kind>: <message>`.
/// For the direct reads `<message>` is the text users have always been shown
/// (`Composio v3 connected_accounts failed: HTTP 401: Invalid API key`), and the
/// host's invalid-key gate and failure classification key on it, so it must come
/// back exactly. Anything not shaped like a member failure (the module could
/// not be loaded or reached) is returned unchanged.
#[must_use]
pub fn member_failure_message(member: &str, error: &str) -> String {
    const WIRE_ERROR_PREFIX: &str = "ai.tinyhumans.tinybus.Error.";
    let Some(mut message) = error
        .strip_prefix(member)
        .and_then(|rest| rest.strip_prefix(": "))
    else {
        return error.to_string();
    };
    while let Some(tail) = message
        .strip_prefix(WIRE_ERROR_PREFIX)
        .and_then(|rest| rest.split_once(": ").map(|(_, tail)| tail))
    {
        message = tail;
    }
    message.to_string()
}

/// Call a member that takes no arguments.
///
/// # Errors
///
/// As [`call`].
#[cfg(feature = "modules")]
pub async fn call_bare<Reply: serde::de::DeserializeOwned>(
    config: &crate::config::Config,
    member: &str,
) -> Result<Reply, String> {
    prime_curated_catalogs(config).await;
    crate::modules::connectors::call_bare(config, member)
        .await
        .map_err(|error| normalize_error(member, error))
}

/// Call a member that takes no arguments. Always fails without `modules`.
///
/// # Errors
///
/// Always, explaining that this build has no module loader.
#[cfg(not(feature = "modules"))]
pub async fn call_bare<Reply: serde::de::DeserializeOwned>(
    _config: &crate::config::Config,
    member: &str,
) -> Result<Reply, String> {
    crate::modules::client(_config.clone())
        .call::<Reply>("tinyconnectors", member, ())
        .await
        .map_err(|error| format!("{member}: {error}; {WITHOUT_MODULES}"))
}

/// Serializes every test that reaches the connector module.
///
/// The module is loaded once per process and holds exactly one route, but each
/// test that exercises it stands up its own mock backend on its own port and
/// points the module at it. Run in parallel they reconfigure each other
/// mid-call, and the failure surfaces as a 404 from somebody else's mock —
/// which reads like a bug in the code under test rather than as a race.
///
/// This did not exist before the connector extraction, because each test built
/// its own client. Sharing one module instance is the price of the module
/// being real in these tests rather than mocked, and they are worth more for
/// it: they exercise the loader, the bus, and the module's own dispatch.
///
/// It lives here rather than in one test module because the tests that need it
/// are spread across `ops_tests` and the flow adapter's own suite, and two
/// locks would serialize neither against the other.
#[cfg(test)]
pub(crate) static MODULE_LOCK: tokio::sync::Mutex<()> = tokio::sync::Mutex::const_new(());

/// The module lock, and the storage the module keeps its preferences in.
#[cfg(test)]
pub(crate) struct ModuleGuard {
    // Fields drop in order: the previous module storage comes back before the
    // next test may take the module. Without the module loader there are no
    // module calls to serve.
    #[cfg(feature = "modules")]
    _storage: crate::modules::storage_host::backend_choice::TestModuleStorage,
    _lock: tokio::sync::MutexGuard<'static, ()>,
}

/// Take the module lock for the rest of the test.
///
/// The module refuses a preference call when the host serves no storage, and
/// a module call carries no workspace for the host to fall back to, so the
/// guard serves module calls a fresh memory backend, restored on drop. It is
/// not installed in the process slot: that would make it every concurrent
/// test's storage (MAIN-57).
#[cfg(test)]
pub(crate) async fn module_guard() -> ModuleGuard {
    let lock = module_lock_guard().await;
    ModuleGuard {
        #[cfg(feature = "modules")]
        _storage: crate::modules::storage_host::backend_choice::serve_test_module_storage(
            crate::storage::test_support::memory_backend(),
        ),
        _lock: lock,
    }
}

/// The module lock without [`module_guard`]'s storage, for tests of the
/// process keyring: an installed backend moves user secrets into storage.
#[cfg(test)]
pub(crate) async fn module_lock_guard() -> tokio::sync::MutexGuard<'static, ()> {
    // Tests that take the module drive its backend mode against a local mock;
    // give this thread the stand-in route a host would register.
    super::test_backend_route::register();
    MODULE_LOCK.lock().await
}

#[cfg(test)]
#[path = "module_client_tests.rs"]
mod tests;