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
//! Per-action Composio tool wrapper.
//!
//! A [`ComposioActionTool`] is a [`Tool`] that represents exactly one
//! Composio action (e.g. `GMAIL_SEND_EMAIL`). It holds the action's
//! name, description, and parameter JSON schema so the LLM's native
//! tool-calling path can validate arguments before they hit the wire.
//!
//! [`ComposioActionTool::new`] builds a `ToolExposure::Direct` instance
//! anchored to a config snapshot.
//!
//! [`ComposioActionTool::deferred`] builds the same tool as a
//! `ToolExposure::Deferred` registration for a parent session:
//! every action of every connected toolkit is synthesised beside the
//! delegation tools (`integrations::composio::orchestrator_actions`), stays off the wire, and
//! is found through the harness's `tool_search` bridge — so one clear action
//! ("send Alex a Slack message") is a search and a call, not a sub-agent
//! run. Those instances have no spawn-time config to anchor to and resolve
//! the live config through the core's read path instead.
//!
//! Rather than baking a pre-resolved route at construction time
//! (which would silently bypass a mid-session
//! [`crate::config::ComposioConfig::mode`] toggle — see
//! issue #1710), each tool keeps an [`Arc<Config>`] and resolves the
//! client per call through
//! [`resolve_composio_route`] so a user flip from
//! `mode = "backend"` to `mode = "direct"` is honoured on the next
//! tool invocation without restarting the session. Mirrors the agent-
//! tool migration in
//! [`super::tools::ComposioExecuteTool`].
use crate::core::runtime::DispatchCtx;
use std::sync::Arc;
use async_trait::async_trait;
use serde_json::Value;
use super::contract::ToolScope;
use super::tools::resolve_action_scope;
use crate::agent::tinyagents::host::run_context::{dispatch_ctx_for_tool, sandbox_mode_for_tool};
use crate::config::Config;
use tinyagents_definition::SandboxMode;
use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolCategory, ToolResult, ToolRunContext};
/// A single Composio action exposed as a first-class tool.
pub struct ComposioActionTool {
/// Held instead of a pre-baked a pre-resolved route so
/// the [`crate::config::ComposioConfig::mode`] toggle is
/// honoured on every invocation.
///
/// Pre-fix this field was `client: ComposioClient` (the since-removed in-process client), which captured
/// the backend-bound handle at sub-agent spawn time. Toggling
/// `composio.mode = "direct"` mid-session invalidated other caches
/// but left these per-action tools still routing through
/// the managed backend's composio execute route
/// — silently bypassing the direct-mode user's personal Composio
/// tenant. Resolving the client per call via
/// [`resolve_composio_route`] keeps dispatch in lockstep with the
/// live config, matching
/// [`super::tools::ComposioExecuteTool`]. See issue #1710.
///
/// `None` for a deferred instance synthesised for a parent session,
/// which has no spawn-time config: it resolves the live config through
/// [`DispatchCtx::load_config`] on every call — the
/// embedder's config when one is bound, else the process-global one.
config: Option<Arc<Config>>,
/// Action slug as-shipped to Composio, e.g. `"GMAIL_SEND_EMAIL"`.
action_name: String,
/// Human-readable description from the Composio tool-list response.
description: String,
/// Full JSON schema for the action's parameters. Falls back to
/// `{"type":"object"}` when the upstream response omits it so the
/// LLM still gets a valid (if loose) shape.
parameters: Value,
/// When set, all executions through this tool target a specific
/// Composio connection. Used when the sub-agent is spawned for a
/// particular account (e.g. "send from my work Gmail").
connection_id: Option<String>,
/// Per-turn contract gate (#4853). On the first call to this action the
/// gate surfaces the action's FULL live input schema/description so the
/// model composes well-formed arguments (e.g. correctly-quoted Gmail
/// queries) instead of guessing from the thin spawn-time schema; the retry
/// executes normally. Held per tool instance, so "seen" is scoped to that
/// instance's lifetime.
gate: super::contract_gate::ContractGate,
/// `Direct` for a config-anchored instance, `Deferred` for the
/// parent-session catalogue reached through `tool_search`.
exposure: tinytools::ToolExposure,
/// The toolkit slug (`gmail`, `slack`) for a deferred instance, so the
/// search index can say where an action came from.
family: Option<String>,
}
impl ComposioActionTool {
pub fn new(
config: Arc<Config>,
action_name: String,
description: String,
parameters: Option<Value>,
) -> Self {
Self::with_connection_id(config, action_name, description, parameters, None)
}
pub fn with_connection_id(
config: Arc<Config>,
action_name: String,
description: String,
parameters: Option<Value>,
connection_id: Option<String>,
) -> Self {
Self::build(
Some(config),
action_name,
description,
parameters,
connection_id,
tinytools::ToolExposure::Direct,
None,
)
}
/// A `Deferred` instance for a parent session's searchable catalogue:
/// off the wire, found through `tool_search`, resolving the live config
/// per call. `toolkit` is the slug the action belongs to.
pub fn deferred(
toolkit: &str,
action_name: String,
description: String,
parameters: Option<Value>,
) -> Self {
Self::build(
None,
action_name,
description,
parameters,
None,
tinytools::ToolExposure::Deferred,
Some(toolkit.to_string()),
)
}
fn build(
config: Option<Arc<Config>>,
action_name: String,
description: String,
parameters: Option<Value>,
connection_id: Option<String>,
exposure: tinytools::ToolExposure,
family: Option<String>,
) -> Self {
let parameters = parameters.unwrap_or_else(|| serde_json::json!({"type": "object"}));
Self {
config,
action_name,
description,
parameters,
connection_id,
gate: super::contract_gate::ContractGate::new(),
exposure,
family,
}
}
/// The live config for one call: a reload anchored to the spawn-time
/// snapshot when there is one, else the core's read path.
async fn live_config(&self, ctx: &DispatchCtx) -> Result<Config, String> {
match self.config.as_deref() {
Some(snapshot) => super::tools::live_composio_config(snapshot).await,
None => ctx.load_config().await,
}
}
}
/// Render a Composio action slug (`GMAIL_SEND_EMAIL`) as a sentence-cased
/// human phrase ("Gmail send email") for the chat processing timeline.
fn humanize_composio_action(slug: &str) -> String {
let lower = slug.trim().to_ascii_lowercase().replace('_', " ");
let lower = lower.split_whitespace().collect::<Vec<_>>().join(" ");
let mut chars = lower.chars();
match chars.next() {
Some(first) => first.to_uppercase().collect::<String>() + chars.as_str(),
None => slug.to_string(),
}
}
#[async_trait]
impl Tool for ComposioActionTool {
fn name(&self) -> &str {
&self.action_name
}
fn description(&self) -> &str {
&self.description
}
fn parameters_schema(&self) -> Value {
let mut schema = self.parameters.clone();
if let Some(props) = schema.get_mut("properties").and_then(|v| v.as_object_mut()) {
props.entry("connection_id").or_insert_with(|| {
serde_json::json!({
"type": "string",
"description": "Optional. Target a specific account when multiple are connected. Use the connection_id from Connected Integrations. Omit to use the default."
})
});
}
schema
}
fn permission_level(&self) -> PermissionLevel {
// Conservative default: many actions mutate external state
// (send mail, create issues, modify calendars). Match
// ComposioExecuteTool's write-level treatment so channel
// permission caps behave identically whether the model goes
// through the dispatcher or a per-action tool.
PermissionLevel::Write
}
fn external_effect(&self) -> bool {
super::tools::action_mutates_external_state(&self.action_name)
}
fn category(&self) -> ToolCategory {
ToolCategory::Workflow
}
fn exposure(&self) -> tinytools::ToolExposure {
self.exposure
}
fn family(&self) -> Option<&str> {
self.family.as_deref()
}
fn display_label(&self, _args: &Value) -> Option<String> {
// Composio slugs are UPPER_SNAKE (e.g. `GMAIL_SEND_EMAIL`). Render a
// sentence-cased phrase ("Gmail send email") instead of the shouty
// raw slug or a Title-Cased "GMAIL SEND EMAIL". The contextual target
// (recipient/query) is filled by the trait-default `display_detail`.
Some(humanize_composio_action(&self.action_name))
}
async fn execute(&self, args: Value) -> anyhow::Result<ToolResult> {
let (config, outcome) =
Box::pin(self.execute_unredacted(&dispatch_ctx_for_tool(None), args, None)).await;
super::tools::redact_composio_outcome(&config, outcome)
}
async fn execute_with_context(
&self,
args: Value,
_options: ToolCallOptions,
context: Option<&dyn ToolRunContext>,
) -> anyhow::Result<ToolResult> {
let (config, outcome) = Box::pin(self.execute_unredacted(
&dispatch_ctx_for_tool(context),
args,
sandbox_mode_for_tool(context),
))
.await;
super::tools::redact_composio_outcome(&config, outcome)
}
}
impl ComposioActionTool {
/// Returns the config actually used for this call alongside the
/// outcome, so [`Tool::execute`] always redacts against the same
/// credential that dispatched — for both a spawn-time config and a
/// deferred instance with none.
async fn execute_unredacted(
&self,
ctx: &DispatchCtx,
args: Value,
sandbox_mode: Option<SandboxMode>,
) -> (Box<Config>, anyhow::Result<ToolResult>) {
// Boxed from the moment it exists, not just at the return: this
// local is held across every await point below, and `Config` is a
// large top-level struct — inlining it by value in the generated
// async state machine was enough to blow a 2 MiB worker-thread
// stack (the default for both `cargo test` and tokio).
let fallback_config = || Box::new(self.config.as_deref().cloned().unwrap_or_default());
// Agent-level sandbox gate (issue #685, CodeRabbit follow-up on
// PR #904) — mirrors the check in
// [`super::tools::ComposioExecuteTool::execute`] so a read-only
// agent cannot slip a mutating call through the per-action
// surface. The dispatcher path (`composio_execute`) and this
// per-action path are the only two routes to the Composio
// backend; both must honour the same invariant.
if matches!(sandbox_mode, Some(SandboxMode::ReadOnly)) {
let scope = resolve_action_scope(&self.action_name).await;
if matches!(scope, ToolScope::Write | ToolScope::Admin) {
tracing::info!(
tool = %self.action_name,
scope = scope.as_str(),
"[composio][sandbox] per-action execute blocked: agent is read-only, action is {}",
scope.as_str()
);
return (
fallback_config(),
Ok(ToolResult::error(format!(
"{}: action is classified `{}` and is refused because the calling \
agent is in strict read-only mode. Only `read`-scoped actions are \
available to this agent.",
self.action_name,
scope.as_str()
))),
);
}
}
// [#1710 Wave 4 / #4853] Reload the live config snapshot ONCE, up front,
// and use it for BOTH the contract-gate lookup and dispatch. A mid-session
// `composio.mode` / credential / workspace change must route the gate's
// live-catalog fetch and the actual execution through the SAME config;
// consulting the captured spawn-time `self.config` here would let the gate
// resolve (or skip) a contract against stale routing while dispatch used
// fresh routing. Anchored to this tool's original config path rather than
// re-resolving process-global `OPENHUMAN_WORKSPACE` (the tool is scoped to
// the user/workspace it was created for).
let live_config = match self.live_config(ctx).await {
Ok(c) => Box::new(c),
Err(e) => {
tracing::warn!(
tool = %self.action_name,
error = %e,
"[composio] per-action execute: load_config failed"
);
return (
fallback_config(),
Ok(ToolResult::error(format!(
"{}: failed to load live config: {e}",
self.action_name
))),
);
}
};
// Contract gate (#4853): the per-action tool is built from the thin
// spawn-time `list_tools` schema (often `{"type":"object"}` with no
// field descriptions), so the model guesses argument formats — most
// visibly sending unquoted Gmail `query` strings that return zero
// results. On the first call this turn, surface the action's FULL live
// contract (input schema + description) as a recoverable tool error and
// let the retry — now with the schema in context — execute. Degrades to
// a normal execute whenever the contract can't be resolved (see
// `contract_gate::consult`), so an unconfigured/offline client never
// blocks the action. Uses `live_config` so gate routing matches dispatch.
match super::contract_gate::consult(&self.gate, &live_config, &self.action_name, &args)
.await
{
super::contract_gate::GateDecision::Surface(contract) => {
tracing::info!(
tool = %self.action_name,
"[composio][contract-gate] returning full contract before first execute"
);
return (live_config, Ok(ToolResult::error(contract)));
}
super::contract_gate::GateDecision::Proceed => {}
}
// Inject `timeZone` / `singleEvents` defaults for Google
// Calendar list slugs (issue #1714). The per-action surface is
// the spawn-time tool an integrations sub-agent picks when it
// wants a single Composio action, so the same defaults must
// fire here as on the dispatcher path.
let iana = super::googlecalendar_args::current_iana_timezone();
tracing::debug!(
target: "composio",
slug = %self.action_name,
iana = %iana,
"[composio][per-action] applying calendar query defaults pre-dispatch"
);
let args = match super::processing::prepare(
&live_config,
&self.action_name,
Some(args),
Some(iana),
None,
)
.await
{
Ok(args) => args,
Err(error) => return (live_config, Ok(ToolResult::error(error))),
};
let started = std::time::Instant::now();
// Allow the agent to override the baked-in connection_id via args
let runtime_connection_id = args
.as_ref()
.and_then(|v| v.get("connection_id"))
.and_then(|v| v.as_str())
.map(|s| s.trim())
.filter(|s| !s.is_empty())
.map(String::from);
let effective_connection_id = runtime_connection_id
.as_deref()
.or(self.connection_id.as_deref());
// One call for both routes. The module owns the prepare/retry/error
// -mapping pipeline that `execute_dispatch` used to hold here, so a
// direct-mode toggle still takes effect immediately (#1710): the route
// is reconciled from `live_config` on the way through, rather than
// baked into a client this tool captured at construction.
let res = super::module_client::call::<_, super::types::ComposioExecuteResponse>(
&live_config,
tinyconnectors_bus::names::methods::EXECUTE,
super::types::ComposioExecuteRequest {
tool: self.action_name.clone(),
arguments: args,
connection_id: effective_connection_id.map(str::to_string),
},
)
.await;
let elapsed_ms = started.elapsed().as_millis() as u64;
let outcome = match res {
Ok(resp) => {
crate::core::bus::BUS.publish(
crate::core::events::DomainEvent::ComposioActionExecuted {
tool: self.action_name.clone(),
success: resp.successful,
error: resp.error.clone(),
cost_usd: resp.cost_usd,
elapsed_ms,
},
);
// Mirror `ComposioExecuteTool::execute` (composio/tools.rs):
// prefer the backend-rendered `markdownFormatted` for LLM
// consumption when present, fall back to the raw JSON
// envelope on absence or non-success. Keeps both routes
// (dispatcher + per-action) consistent so the model sees
// the same compact transcript regardless of which tool
// surface the agent picked.
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) => {
crate::core::bus::BUS.publish(
crate::core::events::DomainEvent::ComposioActionExecuted {
tool: self.action_name.clone(),
success: false,
error: Some(e.clone()),
cost_usd: 0.0,
elapsed_ms,
},
);
Ok(ToolResult::error(e))
}
};
(live_config, outcome)
}
}
#[cfg(test)]
#[path = "action_tool_tests.rs"]
mod tests;