@customclaw/composio 0.0.1

package/README.md

@@ -0,0 +1,184 @@
+# Composio Tool Router Plugin for OpenClaw
+
+Access 1000+ third-party tools through Composio's unified Tool Router interface.
+
+## Features
+
+- **Search Tools**: Find tools by describing what you want to accomplish
+- **Execute Tools**: Run any tool with authenticated connections
+- **Multi-Execute**: Run up to 50 tools in parallel
+- **Connection Management**: Connect to toolkits via OAuth or API keys
+
+## Supported Integrations
+
+Gmail, Slack, GitHub, Notion, Linear, Jira, HubSpot, Salesforce, Google Drive, Asana, Trello, and 1000+ more.
+
+## Install
+
+```bash
+openclaw plugins install @customclaw/composio
+```
+
+## Configuration
+
+### Option 1: Environment Variable
+
+```bash
+export COMPOSIO_API_KEY=your-api-key
+```
+
+### Option 2: OpenClaw Config
+
+Add to `~/.openclaw/openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "composio": {
+        "enabled": true,
+        "config": {
+          "apiKey": "your-api-key",
+          "defaultUserId": "client-companyname-uuid",
+          "allowedToolkits": ["gmail", "sentry"]
+        }
+      }
+    }
+  }
+}
+```
+
+Get your API key from [platform.composio.dev/settings](https://platform.composio.dev/settings).
+
+## CLI Commands
+
+```bash
+# List available toolkits
+openclaw composio list
+
+# Check connection status
+openclaw composio status
+openclaw composio status github
+
+# Connect to a toolkit (opens auth URL)
+openclaw composio connect github
+openclaw composio connect gmail
+
+# Disconnect from a toolkit
+openclaw composio disconnect github
+
+# Search for tools
+openclaw composio search "send email"
+openclaw composio search "create issue" --toolkit github
+```
+
+## Agent Tools
+
+The plugin provides six tools for agents:
+
+### `composio_search_tools`
+
+Search for tools matching a task description.
+
+```json
+{
+  "query": "send an email with attachment",
+  "toolkits": ["gmail"],
+  "limit": 5
+}
+```
+
+### `composio_execute_tool`
+
+Execute a single tool.
+
+```json
+{
+  "tool_slug": "GMAIL_SEND_EMAIL",
+  "arguments": {
+    "to": "user@example.com",
+    "subject": "Hello",
+    "body": "Message content"
+  }
+}
+```
+
+### `composio_multi_execute`
+
+Execute multiple tools in parallel (up to 50).
+
+```json
+{
+  "executions": [
+    { "tool_slug": "GITHUB_CREATE_ISSUE", "arguments": { "title": "Bug", "repo": "org/repo" } },
+    { "tool_slug": "SLACK_SEND_MESSAGE", "arguments": { "channel": "#dev", "text": "Issue created" } }
+  ]
+}
+```
+
+### `composio_manage_connections`
+
+Manage toolkit connections.
+
+```json
+{
+  "action": "status",
+  "toolkits": ["github", "gmail"]
+}
+```
+
+### `composio_workbench`
+
+Execute Python code in a remote Jupyter sandbox.
+
+### `composio_bash`
+
+Execute bash commands in a remote sandbox.
+
+## Advanced Configuration
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "composio": {
+        "enabled": true,
+        "config": {
+          "apiKey": "your-api-key",
+          "defaultUserId": "user_123",
+          "allowedToolkits": ["github", "gmail", "slack"],
+          "blockedToolkits": ["dangerous-toolkit"]
+        }
+      }
+    }
+  }
+}
+```
+
+## Updating
+
+```bash
+openclaw plugins update @customclaw/composio
+openclaw gateway restart
+```
+
+Gateway restart is required after updates.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm pack  # creates .tgz for local testing
+openclaw plugins install ./customclaw-composio-0.0.1.tgz
+```
+
+## Acknowledgments
+
+This project is based on the Composio plugin from [openclaw-composio](https://github.com/ComposioHQ/openclaw-composio) by ComposioHQ. See [THIRD-PARTY-NOTICES](./THIRD-PARTY-NOTICES) for details.
+
+## Links
+
+- [Composio Documentation](https://docs.composio.dev)
+- [Tool Router Overview](https://docs.composio.dev/tool-router/overview)
+- [Composio Platform](https://platform.composio.dev)

package/THIRD-PARTY-NOTICES

@@ -0,0 +1,31 @@
+This project is based on the Composio plugin from:
+https://github.com/ComposioHQ/openclaw-composio
+
+That repository is a fork of OpenClaw with the Composio plugin added by the
+ComposioHQ team. The repository-level MIT license (Copyright (c) 2025 Peter
+Steinberger) covers the OpenClaw codebase, not the Composio plugin specifically.
+
+The Composio plugin code (under extensions/composio/) was authored by ComposioHQ.
+We include the repo's MIT license below as it covers the repository as a whole:
+
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/cli.d.ts

@@ -0,0 +1,18 @@
+import type { ComposioClient } from "./client.js";
+import type { ComposioConfig } from "./types.js";
+interface PluginLogger {
+    info(msg: string): void;
+    warn(msg: string): void;
+    error(msg: string): void;
+}
+interface RegisterCliOptions {
+    program: any;
+    client: ComposioClient;
+    config: ComposioConfig;
+    logger: PluginLogger;
+}
+/**
+ * Register Composio CLI commands
+ */
+export declare function registerComposioCli({ program, client, config, logger }: RegisterCliOptions): void;
+export {};

package/dist/cli.js

@@ -0,0 +1,162 @@
+/**
+ * Register Composio CLI commands
+ */
+export function registerComposioCli({ program, client, config, logger }) {
+    const composio = program.command("composio").description("Manage Composio Tool Router connections");
+    // openclaw composio list
+    composio
+        .command("list")
+        .description("List available Composio toolkits")
+        .action(async () => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return;
+        }
+        try {
+            const toolkits = await client.listToolkits();
+            console.log("\nAvailable Composio Toolkits:");
+            console.log("─".repeat(40));
+            for (const toolkit of toolkits.sort()) {
+                console.log(`  ${toolkit}`);
+            }
+            console.log(`\nTotal: ${toolkits.length} toolkits`);
+        }
+        catch (err) {
+            logger.error(`Failed to list toolkits: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // openclaw composio status [toolkit]
+    composio
+        .command("status [toolkit]")
+        .description("Check connection status for toolkits")
+        .option("-u, --user-id <userId>", "User ID for session scoping")
+        .action(async (toolkit, options) => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return;
+        }
+        try {
+            const toolkits = toolkit ? [toolkit] : undefined;
+            const statuses = await client.getConnectionStatus(toolkits, options.userId);
+            console.log("\nComposio Connection Status:");
+            console.log("─".repeat(40));
+            if (statuses.length === 0) {
+                console.log("  No connections found");
+            }
+            else {
+                for (const status of statuses) {
+                    const icon = status.connected ? "✓" : "✗";
+                    const state = status.connected ? "connected" : "not connected";
+                    console.log(`  ${icon} ${status.toolkit}: ${state}`);
+                }
+            }
+            console.log();
+        }
+        catch (err) {
+            logger.error(`Failed to get status: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // openclaw composio connect <toolkit>
+    composio
+        .command("connect <toolkit>")
+        .description("Connect to a Composio toolkit (opens auth URL)")
+        .option("-u, --user-id <userId>", "User ID for session scoping")
+        .action(async (toolkit, options) => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return;
+        }
+        try {
+            console.log(`\nInitiating connection to ${toolkit}...`);
+            const result = await client.createConnection(toolkit, options.userId);
+            if ("error" in result) {
+                logger.error(`Failed to create connection: ${result.error}`);
+                return;
+            }
+            console.log("\nAuth URL generated:");
+            console.log("─".repeat(40));
+            console.log(result.authUrl);
+            console.log("\nOpen this URL in your browser to authenticate.");
+            console.log("After authentication, run 'openclaw composio status' to verify.\n");
+            // Try to open URL in browser
+            try {
+                const { exec } = await import("node:child_process");
+                const platform = process.platform;
+                const cmd = platform === "darwin"
+                    ? `open "${result.authUrl}"`
+                    : platform === "win32"
+                        ? `start "" "${result.authUrl}"`
+                        : `xdg-open "${result.authUrl}"`;
+                exec(cmd);
+            }
+            catch {
+                // Silently fail if we can't open browser
+            }
+        }
+        catch (err) {
+            logger.error(`Failed to connect: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // openclaw composio disconnect <toolkit>
+    composio
+        .command("disconnect <toolkit>")
+        .description("Disconnect from a Composio toolkit")
+        .option("-u, --user-id <userId>", "User ID for session scoping")
+        .action(async (toolkit, options) => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return;
+        }
+        try {
+            console.log(`\nDisconnecting from ${toolkit}...`);
+            const result = await client.disconnectToolkit(toolkit, options.userId);
+            if (result.success) {
+                console.log(`Successfully disconnected from ${toolkit}\n`);
+            }
+            else {
+                logger.error(`Failed to disconnect: ${result.error}`);
+            }
+        }
+        catch (err) {
+            logger.error(`Failed to disconnect: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+    // openclaw composio search <query>
+    composio
+        .command("search <query>")
+        .description("Search for tools matching a query")
+        .option("-t, --toolkit <toolkit>", "Limit search to a specific toolkit")
+        .option("-l, --limit <limit>", "Maximum results", "10")
+        .option("-u, --user-id <userId>", "User ID for session scoping")
+        .action(async (query, options) => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return;
+        }
+        try {
+            const limit = parseInt(options.limit, 10) || 10;
+            const toolkits = options.toolkit ? [options.toolkit] : undefined;
+            const results = await client.searchTools(query, {
+                toolkits,
+                limit,
+                userId: options.userId,
+            });
+            console.log(`\nSearch results for "${query}":`);
+            console.log("─".repeat(60));
+            if (results.length === 0) {
+                console.log("  No tools found matching your query");
+            }
+            else {
+                for (const tool of results) {
+                    console.log(`\n  ${tool.slug}`);
+                    console.log(`    Toolkit: ${tool.toolkit}`);
+                    console.log(`    ${tool.description.slice(0, 100)}${tool.description.length > 100 ? "..." : ""}`);
+                }
+            }
+            console.log(`\nTotal: ${results.length} tools found\n`);
+        }
+        catch (err) {
+            logger.error(`Failed to search: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
+}

package/dist/client.d.ts

@@ -0,0 +1,94 @@
+import type { ComposioConfig, ToolSearchResult, ToolExecutionResult, MultiExecutionItem, MultiExecutionResult, ConnectionStatus } from "./types.js";
+/**
+ * Composio client wrapper using Tool Router pattern
+ */
+export declare class ComposioClient {
+    private client;
+    private config;
+    private sessionCache;
+    constructor(config: ComposioConfig);
+    /**
+     * Get the user ID to use for API calls
+     */
+    private getUserId;
+    /**
+     * Get or create a Tool Router session for a user
+     */
+    private getSession;
+    /**
+     * Check if a toolkit is allowed based on config
+     */
+    private isToolkitAllowed;
+    /**
+     * Execute a Tool Router meta-tool
+     */
+    private executeMetaTool;
+    /**
+     * Search for tools matching a query using COMPOSIO_SEARCH_TOOLS
+     */
+    searchTools(query: string, options?: {
+        toolkits?: string[];
+        limit?: number;
+        userId?: string;
+    }): Promise<ToolSearchResult[]>;
+    /**
+     * Execute a single tool using COMPOSIO_MULTI_EXECUTE_TOOL
+     */
+    executeTool(toolSlug: string, args: Record<string, unknown>, userId?: string): Promise<ToolExecutionResult>;
+    /**
+     * Execute multiple tools in parallel using COMPOSIO_MULTI_EXECUTE_TOOL
+     */
+    multiExecute(executions: MultiExecutionItem[], userId?: string): Promise<MultiExecutionResult>;
+    /**
+     * Get connection status for toolkits using session.toolkits()
+     */
+    getConnectionStatus(toolkits?: string[], userId?: string): Promise<ConnectionStatus[]>;
+    /**
+     * Create an auth connection for a toolkit using session.authorize()
+     */
+    createConnection(toolkit: string, userId?: string): Promise<{
+        authUrl: string;
+    } | {
+        error: string;
+    }>;
+    /**
+     * List available toolkits
+     */
+    listToolkits(userId?: string): Promise<string[]>;
+    /**
+     * Disconnect a toolkit
+     */
+    disconnectToolkit(toolkit: string, userId?: string): Promise<{
+        success: boolean;
+        error?: string;
+    }>;
+    /**
+     * Get the assistive prompt for the agent
+     */
+    getAssistivePrompt(userId?: string): Promise<string>;
+    /**
+     * Execute Python code in the remote workbench using COMPOSIO_REMOTE_WORKBENCH
+     */
+    executeWorkbench(code: string, options?: {
+        thought?: string;
+        currentStep?: string;
+        currentStepMetric?: string;
+        userId?: string;
+    }): Promise<{
+        success: boolean;
+        output?: unknown;
+        error?: string;
+    }>;
+    /**
+     * Execute bash commands in the remote sandbox using COMPOSIO_REMOTE_BASH_TOOL
+     */
+    executeBash(command: string, userId?: string): Promise<{
+        success: boolean;
+        output?: unknown;
+        error?: string;
+    }>;
+}
+/**
+ * Create a Composio client instance
+ */
+export declare function createComposioClient(config: ComposioConfig): ComposioClient;