Skip to content

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

17.7 KB
Raw Blame
//! The `composio_execute` agent tool: sandbox/scope gating, calendar and
//! task-recency argument defaults, dispatch through
//! [`super::super::execute_dispatch`], and response shaping.

use std::sync::Arc;

use async_trait::async_trait;
use serde_json::{json, Value};

use super::live_config::live_composio_config;
use super::redact::redact_composio_outcome;
use crate::agent::tinyagents::host::run_context::{
    dispatch_ctx_for_tool, sandbox_mode_for_tool, task_recency_window_for_tool,
};
use crate::config::Config;
use crate::core::runtime::DispatchCtx;
use tinyagents_definition::SandboxMode;
use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolCategory, ToolResult, ToolRunContext};

use super::super::contract::{toolkit_from_slug, ToolScope};
use super::super::ops::load_user_scope_pref;
use super::scope_gate::{
    action_mutates_external_state, evaluate_tool_visibility, resolve_action_scope,
    scope_error_message, ToolDecision,
};

pub struct ComposioExecuteTool {
    /// Held instead of a pre-baked `ComposioClient` so the
    /// [`crate::config::ComposioConfig::mode`] toggle is
    /// honoured on every call.
    ///
    /// The earlier shape stored a backend-bound `ComposioClient` baked
    /// at agent boot. When the user toggled
    /// `composio.mode = "direct"` mid-session the
    /// `ComposioConfigChanged` event invalidated caches, but this tool's
    /// pre-baked client kept routing executions through
    /// the managed backend's composio execute route
    /// — silently bypassing the direct-mode user's personal Composio
    /// tenant. Resolving the route per call in
    /// the connector module keeps dispatch in lockstep with the
    /// live config, matching
    /// [`crate::integrations::composio::ops::composio_execute`]. See
    /// issue #1710.
    config: Arc<Config>,
}

impl ComposioExecuteTool {
    pub fn new(config: Arc<Config>) -> Self {
        Self { config }
    }
}

#[async_trait]
impl Tool for ComposioExecuteTool {
    fn name(&self) -> &str {
        "composio_execute"
    }
    fn description(&self) -> &str {
        "Execute a Composio action by slug. `tool` is the action slug returned from \
         composio_list_tools (e.g. 'GMAIL_SEND_EMAIL'); `arguments` is an object that \
         conforms to that tool's parameter schema. Returns the provider result plus \
         cost (USD)."
    }
    fn parameters_schema(&self) -> Value {
        json!({
            "type": "object",
            "properties": {
                "tool": {
                    "type": "string",
                    "description": "Composio action slug, e.g. 'GMAIL_SEND_EMAIL'."
                },
                "arguments": {
                    "type": "object",
                    "description": "Action-specific arguments. Shape depends on the tool."
                },
                "connection_id": {
                    "type": "string",
                    "description": "Optional. Target a specific account when multiple are connected for a toolkit. Use the connection_id from '## Connected Integrations'. Omit to use the default account."
                }
            },
            "required": ["tool"],
            "additionalProperties": false
        })
    }
    fn permission_level(&self) -> PermissionLevel {
        // Some composio actions send emails, create files, etc. — treat
        // as write-level to respect channel permission caps.
        PermissionLevel::Write
    }
    fn external_effect(&self) -> bool {
        true
    }
    fn external_effect_with_args(&self, args: &Value) -> bool {
        args.get("tool")
            .and_then(Value::as_str)
            .map(str::trim)
            .filter(|slug| !slug.is_empty())
            .map(action_mutates_external_state)
            .unwrap_or(true)
    }
    fn category(&self) -> ToolCategory {
        ToolCategory::Workflow
    }
    async fn execute(&self, args: Value) -> anyhow::Result<ToolResult> {
        let ctx = dispatch_ctx_for_tool(None);
        let (config, outcome) =
            Box::pin(self.execute_unredacted(&ctx, args, None, None, None)).await;
        redact_composio_outcome(&config, outcome)
    }
    async fn execute_with_context(
        &self,
        args: Value,
        _options: ToolCallOptions,
        context: Option<&dyn ToolRunContext>,
    ) -> anyhow::Result<ToolResult> {
        let ctx = dispatch_ctx_for_tool(context);
        let (config, outcome) = Box::pin(
            self.execute_unredacted(
                &ctx,
                args,
                sandbox_mode_for_tool(context),
                task_recency_window_for_tool(context),
                crate::agent::tinyagents::host::run_context::approval_for_tool(context)
                    .chat
                    .as_ref(),
            ),
        )
        .await;
        redact_composio_outcome(&config, outcome)
    }
}

impl ComposioExecuteTool {
    /// Returns the config actually used for dispatch alongside the outcome,
    /// so [`Tool::execute`] redacts against the same credential that ran —
    /// not the possibly-stale snapshot captured when this tool was
    /// registered.
    async fn execute_unredacted(
        &self,
        ctx: &DispatchCtx,
        args: Value,
        sandbox_mode: Option<SandboxMode>,
        task_recency_window: Option<std::time::Duration>,
        chat: Option<&crate::security::approval::ApprovalChatContext>,
    ) -> (Box<Config>, anyhow::Result<ToolResult>) {
        let tool = args
            .get("tool")
            .and_then(|v| v.as_str())
            .unwrap_or("")
            .trim()
            .to_string();
        if tool.is_empty() {
            return (
                Box::new(self.config.as_ref().clone()),
                Ok(ToolResult::error(
                    "composio_execute: 'tool' is required (e.g. GMAIL_SEND_EMAIL)",
                )),
            );
        }
        let arguments = args.get("arguments").cloned();
        let connection_id = args
            .get("connection_id")
            .and_then(|v| v.as_str())
            .unwrap_or("");
        // INFO-level entry log — visible without bumping log level. Logs
        // ARG KEYS only by default so traces don't leak email bodies / PII;
        // the full arg JSON goes through a paired DEBUG log below for deep
        // debugging. Together these let `grep "[composio][execute]"` show
        // the full agent→backend audit trail at default verbosity.
        let arg_keys: Vec<&str> = arguments
            .as_ref()
            .and_then(|v| v.as_object())
            .map(|obj| obj.keys().map(|k| k.as_str()).collect())
            .unwrap_or_default();
        tracing::info!(
            tool = %tool,
            connection_id = %connection_id,
            arg_keys = ?arg_keys,
            "[composio][execute] >> dispatch"
        );
        if let Some(ref args_json) = arguments {
            tracing::debug!(
                tool = %tool,
                args = %args_json,
                "[composio][execute] >> full args (DEBUG)"
            );
        }

        // Agent-level sandbox gate (issue #685) — applies on top of the
        // user's scope preference below. When the currently-executing
        // agent declares `sandbox_mode = "read_only"` in its
        // `agent.toml`, we refuse to dispatch any Write- or Admin-scoped
        // composio action regardless of what the user's scope pref
        // allows, so a strictly-read-only agent (planner, critic,
        // morning_briefing, …) can never mutate user state via the
        // composio surface. `SandboxMode::None` / `Sandboxed` (and the
        // `None` task-local value used by direct CLI / JSON-RPC / unit
        // tests) pass through unchanged.
        if matches!(sandbox_mode, Some(SandboxMode::ReadOnly)) {
            let scope = resolve_action_scope(&tool).await;
            if matches!(scope, ToolScope::Write | ToolScope::Admin) {
                tracing::info!(
                    tool = %tool,
                    scope = scope.as_str(),
                    "[composio][sandbox] execute blocked: agent is read-only, action is {}",
                    scope.as_str()
                );
                return (
                    Box::new(self.config.as_ref().clone()),
                    Ok(ToolResult::error(format!(
                        "composio_execute: action `{tool}` is classified `{}` and is refused \
                         because the calling agent is in strict read-only mode. Only `read`-scoped \
                         actions are available to this agent.",
                        scope.as_str()
                    ))),
                );
            }
        }

        // Enforce per-user scope preferences before delegating to backend.
        // Uses `self.config` rather than the live-reloaded config resolved
        // further down: a scope-pref read is not the direct-mode-toggle
        // hazard the composio client resolution below guards against, and
        // restructuring the reload earlier would move it ahead of the
        // sandbox/task-window setup this function does first.
        match evaluate_tool_visibility(ctx, self.config.as_ref(), &tool).await {
            ToolDecision::Allow | ToolDecision::PassthroughCheckScope { .. } => {}
            ToolDecision::BlockedByScope { scope } => {
                let toolkit = toolkit_from_slug(&tool).unwrap_or_default();
                let pref = load_user_scope_pref(ctx, self.config.as_ref(), &toolkit)
                    .await
                    .ok();
                let msg = scope_error_message(&tool, scope, pref);
                tracing::info!(
                    tool = %tool,
                    toolkit = %toolkit,
                    scope = scope.as_str(),
                    "[composio][scopes] execute blocked by user scope pref"
                );
                return (
                    Box::new(self.config.as_ref().clone()),
                    Ok(ToolResult::error(msg)),
                );
            }
            ToolDecision::NotCurated => {
                let toolkit = toolkit_from_slug(&tool).unwrap_or_default();
                tracing::info!(
                    tool = %tool,
                    toolkit = %toolkit,
                    "[composio][scopes] execute blocked: action not in curated whitelist"
                );
                return (
                    Box::new(self.config.as_ref().clone()),
                    Ok(ToolResult::error(format!(
                        "composio_execute: action `{tool}` is not in the curated whitelist for \
                         toolkit `{toolkit}`. Use composio_list_tools to see available actions."
                    ))),
                );
            }
        }

        // Inject `timeZone` / `singleEvents` defaults for Google
        // Calendar list slugs so the host's IANA zone reaches the API
        // regardless of how the model built the args (issue #1714).
        // No-op for every other slug; respects caller-supplied values.
        let iana = super::super::googlecalendar_args::current_iana_timezone();
        tracing::debug!(
            target: "composio",
            slug = %tool,
            iana = %iana,
            "[composio][dispatcher] applying calendar query defaults pre-dispatch"
        );

        // Task-recency window (morning briefing): when the calling agent
        // installed a window, inject best-effort server-side narrowing for
        // curated task-fetch slugs. No-op for every other slug and for
        // normal chat / CLI / JSON-RPC (window unset → None). The
        // authoritative enforcement is the post-filter on the response below.
        let task_window_since = task_recency_window.map(|w| {
            chrono::Utc::now()
                - chrono::Duration::from_std(w).unwrap_or_else(|_| chrono::Duration::zero())
        });
        let arguments = match super::super::processing::prepare(
            self.config.as_ref(),
            &tool,
            arguments,
            Some(iana),
            task_window_since.map(|since| since.to_rfc3339()),
        )
        .await
        {
            Ok(arguments) => arguments,
            Err(error) => {
                return (
                    Box::new(self.config.as_ref().clone()),
                    Ok(ToolResult::error(error)),
                )
            }
        };

        // Resolve the client through the mode-aware factory on every
        // call so a direct-mode toggle takes effect immediately
        // (#1710). The pre-baked-client variant of this code routed all
        // executions through the backend tinyhumans tenant regardless
        // of mode — silently breaking direct mode for tool execution.
        let live_config = match live_composio_config(self.config.as_ref()).await {
            Ok(c) => Box::new(c),
            Err(e) => {
                tracing::warn!(error = %e, "[composio] tool execute.execute: load_config failed");
                return (
                    Box::new(self.config.as_ref().clone()),
                    Ok(ToolResult::error(format!(
                        "composio_execute: failed to load live config: {e}"
                    ))),
                );
            }
        };
        let started = std::time::Instant::now();
        // Egress gate + module call (prepare -> retry -> error mapping run in
        // the connector module, mode-aware over the backend/direct split
        // (#1710, #1797)).
        let res = super::super::execute_dispatch::execute_composio_action(
            &live_config,
            chat,
            &tool,
            arguments,
            None,
        )
        .await;
        let elapsed_ms = started.elapsed().as_millis() as u64;
        let outcome = match res {
            Ok(resp) => {
                // Authoritative task-recency enforcement: drop task rows older
                // than the window. No-op unless a window is installed AND the
                // slug is a curated task-fetch action. Runs before the
                // markdown/JSON body decision so the agent reads filtered data.
                let resp = match task_window_since {
                    Some(since) => match super::super::processing::filter(
                        &live_config,
                        &tool,
                        resp,
                        since.to_rfc3339(),
                    )
                    .await
                    {
                        Ok(response) => response,
                        Err(error) => return (live_config, Ok(ToolResult::error(error))),
                    },
                    None => resp,
                };
                tracing::info!(
                    tool = %tool,
                    successful = resp.successful,
                    error = ?resp.error,
                    elapsed_ms,
                    cost_usd = resp.cost_usd,
                    "[composio][execute] << result"
                );
                tracing::debug!(
                    tool = %tool,
                    response = ?resp,
                    "[composio][execute] << full response (DEBUG)"
                );
                crate::core::bus::BUS.publish(
                    crate::core::events::DomainEvent::ComposioActionExecuted {
                        tool: tool.clone(),
                        success: resp.successful,
                        error: resp.error.clone(),
                        cost_usd: resp.cost_usd,
                        elapsed_ms,
                    },
                );
                // Prefer the backend-rendered markdown when available
                // (tinyhumansai/backend#683). The backend handles parsing
                // for all composio actions; if a tool isn't formatted
                // server-side `markdown_formatted` is None and we fall
                // back to the raw JSON envelope.
                let body = if resp.successful {
                    match resp
                        .markdown_formatted
                        .as_deref()
                        .map(str::trim)
                        .filter(|s| !s.is_empty())
                    {
                        Some(md) => md.to_string(),
                        None => serde_json::to_string(&resp).unwrap_or_else(|_| "{}".into()),
                    }
                } else {
                    serde_json::to_string(&resp).unwrap_or_else(|_| "{}".into())
                };
                Ok(ToolResult::success(body))
            }
            Err(e) => {
                tracing::warn!(
                    tool = %tool,
                    error = %e,
                    elapsed_ms,
                    "[composio][execute] << dispatch error"
                );
                crate::core::bus::BUS.publish(
                    crate::core::events::DomainEvent::ComposioActionExecuted {
                        tool: tool.clone(),
                        success: false,
                        error: Some(e.to_string()),
                        cost_usd: 0.0,
                        elapsed_ms,
                    },
                );
                Ok(ToolResult::error(e))
            }
        };
        (live_config, outcome)
    }
}

// NOTE: A `composio_enable_scope` agent-callable meta-tool used to live
// here. It was removed deliberately: scope elevation is a
// security-sensitive, cross-session state change that unlocks
// destructive actions, and putting that flip behind LLM-mediated
// "user consent" both (a) made the safety contract depend on model
// behavior — the weakest place for it — and (b) was a soft gate the
// model could route around (e.g. trash-via-label). The user must
// toggle scopes themselves in **Connections → {toolkit} → {scope}
// row**; the agent only describes the gated capability and points at
// that UI path.
//
// Two surfaces name this policy; keep them in sync:
//   - `GatedIntegrationTool.unlock_paths` populated in `composio::ops`
//   - `scope_error_message` returned from `composio_execute` blocks