@customclaw/composio 0.0.1

package/dist/index.js

@@ -0,0 +1,125 @@
+import { composioPluginConfigSchema, parseComposioConfig } from "./config.js";
+import { createComposioClient } from "./client.js";
+import { createComposioSearchTool } from "./tools/search.js";
+import { createComposioExecuteTool } from "./tools/execute.js";
+import { createComposioMultiExecuteTool } from "./tools/multi-execute.js";
+import { createComposioConnectionsTool } from "./tools/connections.js";
+import { createComposioWorkbenchTool } from "./tools/workbench.js";
+import { createCompositoBashTool } from "./tools/bash.js";
+import { registerComposioCli } from "./cli.js";
+/**
+ * Composio Tool Router Plugin for OpenClaw
+ *
+ * Provides access to 1000+ third-party tools through Composio's unified interface.
+ * Tools include: Gmail, Slack, GitHub, Notion, Linear, Jira, and many more.
+ *
+ * Configuration (in openclaw config):
+ * ```json
+ * {
+ *   "plugins": {
+ *     "composio": {
+ *       "enabled": true,
+ *       "apiKey": "your-composio-api-key"
+ *     }
+ *   }
+ * }
+ * ```
+ *
+ * Or set COMPOSIO_API_KEY environment variable.
+ */
+const composioPlugin = {
+    id: "composio",
+    name: "Composio Tool Router",
+    description: "Access 1000+ third-party tools via Composio Tool Router. " +
+        "Search, authenticate, and execute tools for Gmail, Slack, GitHub, Notion, and more.",
+    configSchema: composioPluginConfigSchema,
+    register(api) {
+        const config = parseComposioConfig(api.pluginConfig);
+        if (!config.enabled) {
+            api.logger.debug("[composio] Plugin disabled in config");
+            return;
+        }
+        if (!config.apiKey) {
+            api.logger.warn("[composio] No API key configured. Set COMPOSIO_API_KEY env var or plugins.composio.apiKey in config.");
+            return;
+        }
+        let client = null;
+        const ensureClient = () => {
+            if (!client) {
+                client = createComposioClient(config);
+            }
+            return client;
+        };
+        // Register tools (lazily create client on first use)
+        api.registerTool({
+            ...createComposioSearchTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createComposioSearchTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        api.registerTool({
+            ...createComposioExecuteTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createComposioExecuteTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        api.registerTool({
+            ...createComposioMultiExecuteTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createComposioMultiExecuteTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        api.registerTool({
+            ...createComposioConnectionsTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createComposioConnectionsTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        api.registerTool({
+            ...createComposioWorkbenchTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createComposioWorkbenchTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        api.registerTool({
+            ...createCompositoBashTool(ensureClient(), config),
+            execute: async (toolCallId, params) => {
+                return createCompositoBashTool(ensureClient(), config).execute(toolCallId, params);
+            },
+        });
+        // Register CLI commands
+        api.registerCli(({ program }) => registerComposioCli({
+            program,
+            client: ensureClient(),
+            config,
+            logger: api.logger,
+        }), { commands: ["composio"] });
+        // Inject agent instructions via before_agent_start hook
+        api.on("before_agent_start", () => {
+            return {
+                prependContext: `<composio-tools>
+You have access to Composio Tool Router, which provides 1000+ third-party integrations (Gmail, Slack, GitHub, Notion, Linear, Jira, HubSpot, Google Drive, etc.).
+
+## How to use Composio tools
+
+1. **Search first**: Use \`composio_search_tools\` to find tools matching the user's task. Search by describing what you want to do (e.g., "send email", "create github issue").
+
+2. **Check connections**: Before executing, use \`composio_manage_connections\` with action="status" to verify the required toolkit is connected. If not connected, use action="create" to generate an auth URL for the user.
+
+3. **Execute tools**: Use \`composio_execute_tool\` with the tool_slug from search results and arguments matching the tool's schema. For multiple operations, use \`composio_multi_execute\` to run up to 50 tools in parallel.
+
+4. **Remote processing**: For large responses or bulk operations, use \`composio_workbench\` to run Python code in a remote Jupyter sandbox with helpers like run_composio_tool(), invoke_llm(), etc. Use \`composio_bash\` for shell commands in the remote sandbox.
+
+## Important notes
+- Tool slugs are uppercase (e.g., GMAIL_SEND_EMAIL, GITHUB_CREATE_ISSUE)
+- Always use exact tool_slug values from search results - do not invent slugs
+- Check the parameters schema from search results before executing
+- If a tool fails with auth errors, prompt the user to connect the toolkit
+- Use workbench/bash tools when processing data stored in remote files or scripting bulk operations
+</composio-tools>`,
+            };
+        });
+        api.logger.info("[composio] Plugin registered with 6 tools and CLI commands");
+    },
+};
+export default composioPlugin;

package/dist/tools/bash.d.ts

@@ -0,0 +1,42 @@
+import type { ComposioClient } from "../client.js";
+import type { ComposioConfig } from "../types.js";
+/**
+ * Tool parameters for composio_bash
+ */
+export declare const CompositoBashSchema: import("@sinclair/typebox").TObject<{
+    command: import("@sinclair/typebox").TString;
+    user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Create the composio_bash tool
+ */
+export declare function createCompositoBashTool(client: ComposioClient, _config: ComposioConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        command: import("@sinclair/typebox").TString;
+        user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            error: string;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            output: unknown;
+            success: boolean;
+        } | {
+            error: string | undefined;
+            success: boolean;
+        };
+    }>;
+};

package/dist/tools/bash.js

@@ -0,0 +1,59 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * Tool parameters for composio_bash
+ */
+export const CompositoBashSchema = Type.Object({
+    command: Type.String({
+        description: "Bash command to execute in the remote sandbox. " +
+            "Use for file operations, data processing with jq/awk/sed/grep, " +
+            "or handling large tool responses saved to remote files. " +
+            "Commands run from /home/user directory by default.",
+    }),
+    user_id: Type.Optional(Type.String({
+        description: "User ID for session scoping (uses default if not provided)",
+    })),
+});
+/**
+ * Create the composio_bash tool
+ */
+export function createCompositoBashTool(client, _config) {
+    return {
+        name: "composio_bash",
+        label: "Composio Remote Bash",
+        description: "Execute bash commands in a remote sandbox for file operations, data processing, " +
+            "and system tasks. Essential for handling large tool responses saved to remote files. " +
+            "Use shell tools like jq, awk, sed, grep for data extraction.",
+        parameters: CompositoBashSchema,
+        async execute(_toolCallId, params) {
+            const command = String(params.command || "").trim();
+            if (!command) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "command is required" }, null, 2) }],
+                    details: { error: "command is required" },
+                };
+            }
+            const userId = typeof params.user_id === "string" ? params.user_id : undefined;
+            try {
+                const result = await client.executeBash(command, userId);
+                const response = {
+                    success: result.success,
+                    ...(result.success ? { output: result.output } : { error: result.error }),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                    details: response,
+                };
+            }
+            catch (err) {
+                const errorResponse = {
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(errorResponse, null, 2) }],
+                    details: errorResponse,
+                };
+            }
+        },
+    };
+}

package/dist/tools/connections.d.ts

@@ -0,0 +1,89 @@
+import type { ComposioClient } from "../client.js";
+import type { ComposioConfig } from "../types.js";
+/**
+ * Tool parameters for composio_manage_connections
+ */
+export declare const ComposioManageConnectionsToolSchema: import("@sinclair/typebox").TObject<{
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">]>;
+    toolkit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+    user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Create the composio_manage_connections tool
+ */
+export declare function createComposioConnectionsTool(client: ComposioClient, _config: ComposioConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">]>;
+        toolkit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
+        user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            count: number;
+            toolkits: string[];
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            error: string;
+            action?: undefined;
+            toolkit?: undefined;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            toolkit: string;
+            error: string;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            toolkit: string;
+            authUrl: string;
+            instructions: string;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            count: number;
+            connections: {
+                toolkit: string;
+                connected: boolean;
+            }[];
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            error: string;
+        };
+    }>;
+};

package/dist/tools/connections.js

@@ -0,0 +1,112 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * Tool parameters for composio_manage_connections
+ */
+export const ComposioManageConnectionsToolSchema = Type.Object({
+    action: Type.Union([Type.Literal("status"), Type.Literal("create"), Type.Literal("list")], {
+        description: "Action to perform: 'status' to check connections, 'create' to initiate auth, 'list' to list toolkits",
+    }),
+    toolkit: Type.Optional(Type.String({
+        description: "Toolkit name for 'status' or 'create' actions (e.g., 'github', 'gmail')",
+    })),
+    toolkits: Type.Optional(Type.Array(Type.String(), {
+        description: "Multiple toolkits to check status for",
+    })),
+    user_id: Type.Optional(Type.String({
+        description: "User ID for session scoping (uses default if not provided)",
+    })),
+});
+/**
+ * Create the composio_manage_connections tool
+ */
+export function createComposioConnectionsTool(client, _config) {
+    return {
+        name: "composio_manage_connections",
+        label: "Composio Manage Connections",
+        description: "Manage Composio toolkit connections. Check connection status, create new auth links, " +
+            "or list available toolkits. Use this before executing tools to ensure authentication.",
+        parameters: ComposioManageConnectionsToolSchema,
+        async execute(_toolCallId, params) {
+            const action = String(params.action || "status");
+            const userId = typeof params.user_id === "string" ? params.user_id : undefined;
+            try {
+                switch (action) {
+                    case "list": {
+                        const toolkits = await client.listToolkits();
+                        const response = {
+                            action: "list",
+                            count: toolkits.length,
+                            toolkits,
+                        };
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                            details: response,
+                        };
+                    }
+                    case "create": {
+                        const toolkit = String(params.toolkit || "").trim();
+                        if (!toolkit) {
+                            return {
+                                content: [
+                                    { type: "text", text: JSON.stringify({ error: "toolkit is required for 'create' action" }, null, 2) },
+                                ],
+                                details: { error: "toolkit is required for 'create' action" },
+                            };
+                        }
+                        const result = await client.createConnection(toolkit, userId);
+                        if ("error" in result) {
+                            return {
+                                content: [{ type: "text", text: JSON.stringify({ action: "create", toolkit, error: result.error }, null, 2) }],
+                                details: { action: "create", toolkit, error: result.error },
+                            };
+                        }
+                        const response = {
+                            action: "create",
+                            toolkit,
+                            authUrl: result.authUrl,
+                            instructions: `Open the auth URL to connect ${toolkit}. After authentication, the connection will be active.`,
+                        };
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                            details: response,
+                        };
+                    }
+                    case "status":
+                    default: {
+                        // Collect toolkits to check
+                        let toolkitsToCheck;
+                        if (typeof params.toolkit === "string" && params.toolkit.trim()) {
+                            toolkitsToCheck = [params.toolkit.trim()];
+                        }
+                        else if (Array.isArray(params.toolkits)) {
+                            toolkitsToCheck = params.toolkits.filter((t) => typeof t === "string" && t.trim() !== "");
+                        }
+                        const statuses = await client.getConnectionStatus(toolkitsToCheck, userId);
+                        const response = {
+                            action: "status",
+                            count: statuses.length,
+                            connections: statuses.map((s) => ({
+                                toolkit: s.toolkit,
+                                connected: s.connected,
+                            })),
+                        };
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                            details: response,
+                        };
+                    }
+                }
+            }
+            catch (err) {
+                const errorResponse = {
+                    action,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(errorResponse, null, 2) }],
+                    details: errorResponse,
+                };
+            }
+        },
+    };
+}

package/dist/tools/execute.d.ts

@@ -0,0 +1,46 @@
+import type { ComposioClient } from "../client.js";
+import type { ComposioConfig } from "../types.js";
+/**
+ * Tool parameters for composio_execute_tool
+ */
+export declare const ComposioExecuteToolSchema: import("@sinclair/typebox").TObject<{
+    tool_slug: import("@sinclair/typebox").TString;
+    arguments: import("@sinclair/typebox").TUnknown;
+    user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Create the composio_execute_tool tool
+ */
+export declare function createComposioExecuteTool(client: ComposioClient, _config: ComposioConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        tool_slug: import("@sinclair/typebox").TString;
+        arguments: import("@sinclair/typebox").TUnknown;
+        user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            error: string;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            data: unknown;
+            tool_slug: string;
+            success: boolean;
+        } | {
+            error: string | undefined;
+            tool_slug: string;
+            success: boolean;
+        };
+    }>;
+};

package/dist/tools/execute.js

@@ -0,0 +1,63 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * Tool parameters for composio_execute_tool
+ */
+export const ComposioExecuteToolSchema = Type.Object({
+    tool_slug: Type.String({
+        description: "Tool slug from composio_search_tools results (e.g., 'GMAIL_SEND_EMAIL')",
+    }),
+    arguments: Type.Unknown({
+        description: "Tool arguments matching the tool's parameter schema",
+    }),
+    user_id: Type.Optional(Type.String({
+        description: "User ID for session scoping (uses default if not provided)",
+    })),
+});
+/**
+ * Create the composio_execute_tool tool
+ */
+export function createComposioExecuteTool(client, _config) {
+    return {
+        name: "composio_execute_tool",
+        label: "Composio Execute Tool",
+        description: "Execute a single Composio tool. Use composio_search_tools first to find the tool slug " +
+            "and parameter schema. The tool must be connected (use composio_manage_connections to check).",
+        parameters: ComposioExecuteToolSchema,
+        async execute(_toolCallId, params) {
+            const toolSlug = String(params.tool_slug || "").trim();
+            if (!toolSlug) {
+                return {
+                    content: [{ type: "text", text: JSON.stringify({ error: "tool_slug is required" }, null, 2) }],
+                    details: { error: "tool_slug is required" },
+                };
+            }
+            const args = params.arguments && typeof params.arguments === "object" && !Array.isArray(params.arguments)
+                ? params.arguments
+                : {};
+            const userId = typeof params.user_id === "string" ? params.user_id : undefined;
+            try {
+                const result = await client.executeTool(toolSlug, args, userId);
+                const response = {
+                    tool_slug: toolSlug,
+                    success: result.success,
+                    ...(result.success ? { data: result.data } : { error: result.error }),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                    details: response,
+                };
+            }
+            catch (err) {
+                const errorResponse = {
+                    tool_slug: toolSlug,
+                    success: false,
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(errorResponse, null, 2) }],
+                    details: errorResponse,
+                };
+            }
+        },
+    };
+}

package/dist/tools/multi-execute.d.ts

@@ -0,0 +1,52 @@
+import type { ComposioClient } from "../client.js";
+import type { ComposioConfig } from "../types.js";
+/**
+ * Tool parameters for composio_multi_execute
+ */
+export declare const ComposioMultiExecuteToolSchema: import("@sinclair/typebox").TObject<{
+    executions: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        tool_slug: import("@sinclair/typebox").TString;
+        arguments: import("@sinclair/typebox").TUnknown;
+    }>>;
+    user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/**
+ * Create the composio_multi_execute tool
+ */
+export declare function createComposioMultiExecuteTool(client: ComposioClient, _config: ComposioConfig): {
+    name: string;
+    label: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        executions: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+            tool_slug: import("@sinclair/typebox").TString;
+            arguments: import("@sinclair/typebox").TUnknown;
+        }>>;
+        user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>;
+    execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            error: string;
+        };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            total: number;
+            succeeded: number;
+            failed: number;
+            results: {
+                tool_slug: string;
+                success: boolean;
+                data?: unknown;
+                error?: string;
+            }[];
+        };
+    }>;
+};

package/dist/tools/multi-execute.js

@@ -0,0 +1,87 @@
+import { Type } from "@sinclair/typebox";
+/**
+ * Tool parameters for composio_multi_execute
+ */
+export const ComposioMultiExecuteToolSchema = Type.Object({
+    executions: Type.Array(Type.Object({
+        tool_slug: Type.String({
+            description: "Tool slug from composio_search_tools results",
+        }),
+        arguments: Type.Unknown({
+            description: "Tool arguments matching the tool's parameter schema",
+        }),
+    }), {
+        description: "Array of tool executions to run in parallel (max 50)",
+        maxItems: 50,
+    }),
+    user_id: Type.Optional(Type.String({
+        description: "User ID for session scoping (uses default if not provided)",
+    })),
+});
+/**
+ * Create the composio_multi_execute tool
+ */
+export function createComposioMultiExecuteTool(client, _config) {
+    return {
+        name: "composio_multi_execute",
+        label: "Composio Multi Execute",
+        description: "Execute multiple Composio tools in parallel (up to 50). Use composio_search_tools first " +
+            "to find tool slugs and parameter schemas. All tools must be connected.",
+        parameters: ComposioMultiExecuteToolSchema,
+        async execute(_toolCallId, params) {
+            const executions = Array.isArray(params.executions) ? params.executions : [];
+            if (executions.length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ error: "executions array is required and cannot be empty" }, null, 2) },
+                    ],
+                    details: { error: "executions array is required and cannot be empty" },
+                };
+            }
+            // Validate and normalize executions
+            const normalizedExecutions = executions
+                .slice(0, 50)
+                .filter((exec) => exec &&
+                typeof exec === "object" &&
+                typeof exec.tool_slug === "string" &&
+                exec.tool_slug.trim() !== "")
+                .map((exec) => ({
+                tool_slug: exec.tool_slug.trim(),
+                arguments: exec.arguments && typeof exec.arguments === "object" && !Array.isArray(exec.arguments)
+                    ? exec.arguments
+                    : {},
+            }));
+            if (normalizedExecutions.length === 0) {
+                return {
+                    content: [
+                        { type: "text", text: JSON.stringify({ error: "No valid executions provided" }, null, 2) },
+                    ],
+                    details: { error: "No valid executions provided" },
+                };
+            }
+            const userId = typeof params.user_id === "string" ? params.user_id : undefined;
+            try {
+                const result = await client.multiExecute(normalizedExecutions, userId);
+                const response = {
+                    total: normalizedExecutions.length,
+                    succeeded: result.results.filter((r) => r.success).length,
+                    failed: result.results.filter((r) => !r.success).length,
+                    results: result.results,
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                    details: response,
+                };
+            }
+            catch (err) {
+                const errorResponse = {
+                    error: err instanceof Error ? err.message : String(err),
+                };
+                return {
+                    content: [{ type: "text", text: JSON.stringify(errorResponse, null, 2) }],
+                    details: errorResponse,
+                };
+            }
+        },
+    };
+}