composio-patterns

# Composio Integration Patterns ## What It Does Reference conventions for yellow-composio plugin -- tool patterns, batch processing, usage tracking, graceful degradation, and security rules. ## When to Use Use when authoring or modifying commands or agents that call Composio tools -- the Workbench sandbox, Multi-Execute batching, and the local usage counter. ## Usage Reference the sections below as preloaded context; start with the Overview for the three-prefix tool discovery order. ## Overview Composio is a managed tool integration platform providing 1,000+ toolkits and 11,000+ actions via a single MCP server. In yellow-plugins, Composio is an **optional accelerator** -- all workflows must function without it. Tools are discovered via ToolSearch and may appear under one of three prefixes, checked in priority order: 1. `mcp__plugin_yellow-composio_composio-server__*` -- bundled by this plugin (preferred, requires both `userConfig` values to be set). 2. `mcp__claude_ai_composio__*` -- Claude.ai native Composio integration (legacy, still supported). 3. `mcp__composio-server__*` -- manual `claude mcp add` setup (legacy / migration path). ## Tool Reference ### Meta Tools (Always Available in Composio Session) | Tool | Slug | Purpose | |------|------|---------| | Search Tools | `COMPOSIO_SEARCH_TOOLS` | Discover tools, get schemas, check connection status | | Get Schemas | `COMPOSIO_GET_TOOL_SCHEMAS` | Full parameter schemas for specific tools | | Multi-Execute | `COMPOSIO_MULTI_EXECUTE_TOOL` | Run up to 50 tools in parallel | | Manage Connections | `COMPOSIO_MANAGE_CONNECTIONS` | OAuth flow, API key auth for apps | | Remote Workbench | `COMPOSIO_REMOTE_WORKBENCH` | Persistent Python sandbox (Jupyter-style) | | Remote Bash | `COMPOSIO_REMOTE_BASH_TOOL` | Bash commands in the sandbox | ### Additional Meta Tools | Tool | Purpose | |------|---------| | `COMPOSIO_CREATE_PLAN` | Generate execution plans for complex tasks | | `COMPOSIO_WAIT_FOR_CONNECTIONS` | Pause for user auth completion | | `COMPOSIO_LIST_TOOLKITS` | List all available toolkits with filters | | `COMPOSIO_EXECUTE_AGENT` | Execute complex multi-step workflows | | `COMPOSIO_GET_TOOL_DEPENDENCY_GRAPH` | Related/parent tool discovery | ### App-Specific Tools Follow `{TOOLKIT}_{ACTION}` naming (e.g., `GMAIL_SEND_EMAIL`, `GITHUB_CREATE_ISSUE`). Discovered at runtime via `COMPOSIO_SEARCH_TOOLS` -- never hardcode app-specific tool slugs. ## Workbench Batch Processing Pattern Use `COMPOSIO_REMOTE_WORKBENCH` when processing 10+ items, handling large API responses, or performing data transformation that would consume excessive context tokens. ### When to Use - Fetching and classifying 10+ items (Linear issues, semgrep findings, etc.) - Aggregating results from multiple API calls - Data transformation, filtering, and summarization - Any operation where raw response data would overwhelm context ### Session Lifecycle 1. **Get session_id** from `COMPOSIO_SEARCH_TOOLS` response (`session.id`) 2. **Execute code** via `COMPOSIO_REMOTE_WORKBENCH` with `session_id` 3. **State persists** across calls within the same session 4. **Each operation creates its own session** (no reuse across workflow steps in v1 -- avoids state leakage) ### Built-in Helpers Available inside `COMPOSIO_REMOTE_WORKBENCH` code: | Helper | Purpose | |--------|---------| | `run_composio_tool(slug, args)` | Execute any Composio tool; returns `(response, error)` | | `invoke_llm(query)` | Call LLM for classification/summarization (max 200K chars) | | `upload_local_file(*paths)` | Upload files to cloud storage; returns download URL | | `proxy_execute(method, endpoint, toolkit)` | Direct API calls when no tool exists | | `web_search` | Search the web for data enrichment | | `smart_file_extract` | Extract text from PDFs, images, documents | ### Parallelism Pattern ```python from concurrent.futures import ThreadPoolExecutor items = [...] # list of items to process results = [] def process_item(item): response, error = run_composio_tool("TOOL_SLUG", {"arg": item}) return {"item": item, "result": response, "error": error} with ThreadPoolExecutor(max_workers=10) as executor: results = list(executor.map(process_item, items)) ``` ### Context Window Management Use `sync_response_to_workbench=true` on `COMPOSIO_MULTI_EXECUTE_TOOL` to save large responses to the remote sandbox instead of returning them inline. Then process via `COMPOSIO_REMOTE_WORKBENCH` or `COMPOSIO_REMOTE_BASH_TOOL`. ### Chunked Execution for Large Batches Workbench has a **hard 4-minute timeout** per execution. For batches exceeding this: 1. Split work into chunks of N items (start with N=20, adjust based on per-item processing time) 2. Execute each chunk in a separate Workbench call 3. State persists across calls within the same session_id 4. Aggregate results across chunks after all complete ### Remote File Path Warning Paths returned from Workbench (e.g., `/home/user/.code_out/response.json`) are **REMOTE** -- they exist only in the sandbox. Never use them as local file paths. To get data out of the sandbox, return it inline from the Python code or use `upload_local_file()` for large artifacts. ## Multi-Execute Pattern `COMPOSIO_MULTI_EXECUTE_TOOL` runs up to 50 independent tool calls in parallel. ### Rules - Use valid tool slugs from `COMPOSIO_SEARCH_TOOLS` -- never invent slugs - Ensure ACTIVE connections for all toolkits being called - Only batch logically independent operations (no ordering dependencies) - Do not pass dummy or placeholder values ### Workflow ```text COMPOSIO_SEARCH_TOOLS -> COMPOSIO_MANAGE_CONNECTIONS (if needed) -> COMPOSIO_MULTI_EXECUTE_TOOL ``` ## Usage Tracking Convention ### Schema `.claude/composio-usage.json`: ```json { "version": 1, "created": "ISO8601", "updated": "ISO8601", "thresholds": { "daily_warn": 200, "monthly_warn": 8000 }, "periods": { "YYYY-MM": { "total": 0, "by_tool": { "TOOL_SLUG": 0 }, "by_day": { "YYYY-MM-DD": 0 } } } } ``` ### Counter Increment Consuming commands should increment the counter after each Composio tool execution using this pattern: ```bash USAGE_FILE=".claude/composio-usage.json" LOCK_FILE="${USAGE_FILE}.lock" # Caller must set TOOL_SLUG before sourcing (e.g., TOOL_SLUG="COMPOSIO_REMOTE_WORKBENCH") : "${TOOL_SLUG:?TOOL_SLUG is required}" TODAY=$(date -u +%Y-%m-%d) MONTH=$(date -u +%Y-%m) do_increment() { if jq --arg tool "$TOOL_SLUG" --arg day "$TODAY" --arg month "$MONTH" ' .updated = (now | todate) | .periods[$month] //= {"total": 0, "by_tool": {}, "by_day": {}} | .periods[$month].total += 1 | .periods[$month].by_tool[$tool] = ((.periods[$month].by_tool[$tool] // 0) + 1) | .periods[$month].by_day[$day] = ((.periods[$month].by_day[$day] // 0) + 1) ' "$USAGE_FILE" > "${USAGE_FILE}.tmp"; then mv "${USAGE_FILE}.tmp" "$USAGE_FILE" else rm -f "${USAGE_FILE}.tmp" return 1 fi } if [ -f "$USAGE_FILE" ]; then if command -v flock >/dev/null 2>&1; then touch "$LOCK_FILE" ( flock -x 200; do_increment ) 200>"$LOCK_FILE" else do_increment fi fi ``` Increment **post-execution** (after confirmed success), not pre-execution. ### Threshold Checking - Warn at 80% of `monthly_warn` (approaching threshold) - Warn when projected monthly usage exceeds `monthly_warn` - Display prominent warning when actual usage reaches `monthly_warn` - Check daily count against `daily_warn` threshold - Never hard-block -- the user owns their budget ## Graceful Degradation Pattern All consuming plugins must detect Composio availability at runtime and fall back silently when absent. ### Detection (Pattern A -- ToolSearch Probe) ```text 1. ToolSearch("COMPOSIO_REMOTE_WORKBENCH") 2. If not found: skip Composio path, use existing local approach 3. If found: proceed with Composio-accelerated path 4. If Composio call fails at runtime: fall back to local approach, note degradation briefly ``` This matches the pattern used by `review:pr` for ruvector/morph detection and by debt scanners for ast-grep detection. ### Consumer Integration Pattern Consuming plugins embed Composio detection inline in their command markdown (not via cross-plugin `skills:` preloading -- no such mechanism exists). Pattern: ```markdown ### Step N: Composio acceleration (optional) 1. Call ToolSearch("COMPOSIO_REMOTE_WORKBENCH"). If not found, skip to Step N+1. 2. [Composio-accelerated operation here] 3. Increment usage counter (see composio-patterns skill for bash snippet) 4. If Composio call fails: fall back to [existing local approach], note degradation briefly. ``` ## Error Handling Catalog | Error | Recovery | |-------|----------| | ToolSearch: no Composio tools | Silent skip, use local codepath | | Tool call: network timeout | Retry once after 2s, then fallback to local | | Tool call: 401 Unauthorized | Log warning, fallback to local, suggest `/composio:setup` | | Tool call: 429 Rate Limited | Wait `Retry-After` header seconds, retry once, then fallback | | Workbench: 4-minute timeout | Log warning, reduce batch size, fallback to local | | Connection not ACTIVE | Log warning, suggest `COMPOSIO_MANAGE_CONNECTIONS` | | MCP server not configured | Run `/composio:setup` | | Usage counter missing | Run `/composio:setup` | | Usage counter corrupted | Run `/composio:setup` to reset | ## Security Notes - **Remote execution**: Workbench executes Python code on Composio's remote infrastructure. Do not send sensitive file contents, credentials, private keys, or proprietary algorithms. Use Workbench for data processing and API orchestration, not as a trusted execution environment. - **API key stored in system keychain**: When the bundled MCP path is used, the `composio_api_key` `userConfig` value is stored in the OS keychain (`sensitive: true`) and sent as the `X-API-Key` header on every request. Never echo, log, or transmit the value. Legacy `mcp__claude_ai_composio__*` and `mcp__composio-server__*` paths use Claude Code's native or manual credential management instead. - **HTTPS-only MCP URL (advisory)**: `composio_mcp_url` MUST start with `https://` — Claude Code sends the API key as the `X-API-Key` header to whatever URL is configured, so a non-HTTPS URL leaks the credential in cleartext. Format is not enforced at the schema level (the Claude Code remote validator does not support `userConfig.<key>.pattern`); the bundled `hooks/check-mcp-url.sh` SessionStart hook prints a warning if the URL is non-HTTPS, but it cannot block the MCP server from attaching first. Treat the warning as a "reconfigure now" signal: open `/plugin`, set the URL to an `https://mcp.composio.dev/*` value, and restart the session. - **Content fencing**: Wrap all Composio responses in `--- begin/end ---` delimiters per repository convention. - **Data transmission**: Tool call parameters and Workbench code are sent to Composio's cloud servers. Review what data is included before execution. - **Sandbox isolation**: Composio's sandbox isolation details (containerization, tenant separation) are not publicly documented. Enterprise tier offers VPC/on-prem deployment for stricter requirements. ## Composio Pricing Reference | Plan | Executions/Month | Price | |------|-----------------|-------| | Free / Hobby | 10,000 | $0 | | Starter | 100,000 | $119/month | | Growth | 2,000,000 | $229/month | | Enterprise | Custom | Custom | Overage: $0.249 per 1,000 additional calls. Premium tools cost ~3x standard.