@customclaw/composio 0.0.7 → 0.0.9

package/README.md

@@ -12,7 +12,13 @@ openclaw plugins install @customclaw/composio
 
 1. Get an API key from [platform.composio.dev/settings](https://platform.composio.dev/settings)
 
-2. Add to `~/.openclaw/openclaw.json`:
+2. Run the guided setup:
+
+```bash
+openclaw composio setup
+```
+
+Or add manually to `~/.openclaw/openclaw.json`:
 
 ```json
 {
@@ -31,14 +37,24 @@ openclaw plugins install @customclaw/composio
 }
 ```
 
-Or set `COMPOSIO_API_KEY` as an environment variable.
+You can also set `COMPOSIO_API_KEY` as an environment variable.
 
 3. Restart the gateway.
 
+If you upgraded from an older config shape where keys like `defaultUserId` or `allowedToolkits`
+were placed directly under `plugins.entries.composio`, rerun:
+
+```bash
+openclaw composio setup
+```
+
+Legacy mixed entry-level config keys are now rejected at runtime.
+
 ## What it does
 
-The plugin gives your agent two tools:
+The plugin gives your agent three tools:
 
+- `composio_search_tools` — discovers relevant Composio actions from natural-language intent
 - `composio_execute_tool` — runs a Composio action (e.g. `GMAIL_FETCH_EMAILS`, `SENTRY_LIST_ISSUES`)
 - `composio_manage_connections` — checks connection status and generates OAuth links when a toolkit isn't connected yet
 
@@ -49,6 +65,7 @@ The agent handles the rest. Ask it to "check my latest emails" and it will call
 ## CLI
 
 ```bash
+openclaw composio setup                                 # interactive setup for ~/.openclaw/openclaw.json
 openclaw composio list --user-id user-123               # list available toolkits for a user scope
 openclaw composio status [toolkit] --user-id user-123   # check connection status in a user scope
 openclaw composio accounts [toolkit]                    # inspect connected accounts (id/user_id/status)
@@ -65,6 +82,10 @@ openclaw composio search "send email" --user-id user-123
 | `defaultUserId` | Default Composio `user_id` scope when `--user-id` is not provided |
 | `allowedToolkits` | Only allow these toolkits (e.g. `["gmail", "sentry"]`) |
 | `blockedToolkits` | Block specific toolkits |
+| `readOnlyMode` | Blocks likely-destructive actions by token matching (delete/update/create/send/etc.); use `allowedToolSlugs` to override safe exceptions |
+| `sessionTags` | Optional Tool Router tags (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) |
+| `allowedToolSlugs` | Optional explicit allowlist of UPPERCASE tool slugs |
+| `blockedToolSlugs` | Explicit denylist of UPPERCASE tool slugs |
 
 ## User ID Scope (Important)
 
@@ -95,6 +116,24 @@ npm run build
 npm test
 ```
 
+### Live Integration Tests (Optional)
+
+```bash
+COMPOSIO_LIVE_TEST=1 \
+COMPOSIO_API_KEY=your_key \
+npm run test:live
+```
+
+Optional env vars for execution/disconnect paths:
+
+- `COMPOSIO_LIVE_USER_ID`
+- `COMPOSIO_LIVE_TOOLKIT` (default: `gmail`)
+- `COMPOSIO_LIVE_TOOL_SLUG`
+- `COMPOSIO_LIVE_TOOL_ARGS` (JSON)
+- `COMPOSIO_LIVE_CONNECTED_ACCOUNT_ID`
+- `COMPOSIO_LIVE_EXPECT_EXECUTE_SUCCESS=1`
+- `COMPOSIO_LIVE_ALLOW_DISCONNECT=1` (destructive, opt-in)
+
 ## Acknowledgments
 
 Based on the Composio plugin from [openclaw-composio](https://github.com/ComposioHQ/openclaw-composio) by ComposioHQ. See [THIRD-PARTY-NOTICES](./THIRD-PARTY-NOTICES).

package/dist/cli.d.ts

@@ -7,12 +7,12 @@ interface PluginLogger {
 }
 interface RegisterCliOptions {
     program: any;
-    client: ComposioClient;
+    getClient?: () => ComposioClient;
     config: ComposioConfig;
     logger: PluginLogger;
 }
 /**
  * Register Composio CLI commands
  */
-export declare function registerComposioCli({ program, client, config, logger }: RegisterCliOptions): void;
+export declare function registerComposioCli({ program, getClient, config, logger }: RegisterCliOptions): void;
 export {};

package/dist/cli.js

@@ -1,20 +1,253 @@
+import os from "node:os";
+import path from "node:path";
+import process from "node:process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { isRecord, normalizeToolkitList, normalizeToolkitSlug, stripLegacyFlatConfigKeys, } from "./utils.js";
+const DEFAULT_OPENCLAW_CONFIG_PATH = path.join(os.homedir(), ".openclaw", "openclaw.json");
+const COMPOSIO_PLUGIN_ID = "composio";
+function parseCsvToolkits(value) {
+    if (!value)
+        return undefined;
+    return normalizeToolkitList(value.split(","));
+}
+function parseBooleanLike(value) {
+    const raw = value.trim().toLowerCase();
+    if (!raw)
+        return undefined;
+    if (["1", "true", "yes", "y"].includes(raw))
+        return true;
+    if (["0", "false", "no", "n"].includes(raw))
+        return false;
+    return undefined;
+}
+function normalizePluginIdList(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const normalized = value
+        .filter((item) => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean);
+    return Array.from(new Set(normalized));
+}
+async function readOpenClawConfig(configPath) {
+    try {
+        const raw = await readFile(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        return isRecord(parsed) ? parsed : {};
+    }
+    catch (err) {
+        const nodeErr = err;
+        if (nodeErr?.code === "ENOENT")
+            return {};
+        throw err;
+    }
+}
 /**
  * Register Composio CLI commands
  */
-export function registerComposioCli({ program, client, config, logger }) {
+export function registerComposioCli({ program, getClient, config, logger }) {
     const composio = program.command("composio").description("Manage Composio Tool Router connections");
+    const requireClient = () => {
+        if (!config.enabled) {
+            logger.error("Composio plugin is disabled");
+            return null;
+        }
+        if (!getClient) {
+            logger.error("Composio API key is not configured. Run 'openclaw composio setup' first.");
+            return null;
+        }
+        try {
+            return getClient();
+        }
+        catch (err) {
+            logger.error(`Failed to initialize Composio client: ${err instanceof Error ? err.message : String(err)}`);
+            return null;
+        }
+    };
+    // openclaw composio setup
+    composio
+        .command("setup")
+        .description("Create or update Composio config in ~/.openclaw/openclaw.json")
+        .option("-c, --config-path <path>", "OpenClaw config file path", DEFAULT_OPENCLAW_CONFIG_PATH)
+        .option("--api-key <apiKey>", "Composio API key")
+        .option("--default-user-id <userId>", "Default user ID for Composio user scoping")
+        .option("--allowed-toolkits <toolkits>", "Comma-separated allowed toolkit slugs")
+        .option("--blocked-toolkits <toolkits>", "Comma-separated blocked toolkit slugs")
+        .option("--read-only <enabled>", "Enable read-only mode (true/false)")
+        .option("-y, --yes", "Skip prompts and use defaults/provided values")
+        .action(async (options) => {
+        const configPath = path.resolve(options.configPath || DEFAULT_OPENCLAW_CONFIG_PATH);
+        try {
+            const openClawConfig = await readOpenClawConfig(configPath);
+            const plugins = isRecord(openClawConfig.plugins) ? { ...openClawConfig.plugins } : {};
+            let updatedPluginSystemEnabled = false;
+            let addedToAllowlist = false;
+            let removedFromDenylist = false;
+            if (plugins.enabled === false) {
+                plugins.enabled = true;
+                updatedPluginSystemEnabled = true;
+            }
+            const allow = normalizePluginIdList(plugins.allow);
+            if (allow && allow.length > 0) {
+                const hasExactComposio = allow.includes(COMPOSIO_PLUGIN_ID);
+                const normalizedAllow = allow.filter((id) => id.toLowerCase() !== COMPOSIO_PLUGIN_ID);
+                normalizedAllow.push(COMPOSIO_PLUGIN_ID);
+                plugins.allow = Array.from(new Set(normalizedAllow));
+                if (!hasExactComposio) {
+                    addedToAllowlist = true;
+                }
+            }
+            const deny = normalizePluginIdList(plugins.deny);
+            if (deny && deny.length > 0) {
+                const filteredDeny = deny.filter((id) => id.toLowerCase() !== COMPOSIO_PLUGIN_ID);
+                if (filteredDeny.length !== deny.length) {
+                    removedFromDenylist = true;
+                }
+                if (filteredDeny.length > 0) {
+                    plugins.deny = filteredDeny;
+                }
+                else {
+                    delete plugins.deny;
+                }
+            }
+            const entries = isRecord(plugins.entries) ? { ...plugins.entries } : {};
+            const existingComposioEntry = isRecord(entries.composio) ? { ...entries.composio } : {};
+            const existingComposioConfig = isRecord(existingComposioEntry.config)
+                ? { ...existingComposioEntry.config }
+                : {};
+            let apiKey = String(options.apiKey || "").trim() ||
+                String(existingComposioConfig.apiKey || "").trim() ||
+                String(config.apiKey || "").trim() ||
+                String(process.env.COMPOSIO_API_KEY || "").trim();
+            let defaultUserId = String(options.defaultUserId || "").trim() ||
+                String(existingComposioConfig.defaultUserId || "").trim() ||
+                String(config.defaultUserId || "").trim();
+            let allowedToolkits = parseCsvToolkits(options.allowedToolkits) ||
+                (Array.isArray(existingComposioConfig.allowedToolkits)
+                    ? normalizeToolkitList(existingComposioConfig.allowedToolkits)
+                    : normalizeToolkitList(config.allowedToolkits));
+            let blockedToolkits = parseCsvToolkits(options.blockedToolkits) ||
+                (Array.isArray(existingComposioConfig.blockedToolkits)
+                    ? normalizeToolkitList(existingComposioConfig.blockedToolkits)
+                    : normalizeToolkitList(config.blockedToolkits));
+            let readOnlyMode = typeof existingComposioConfig.readOnlyMode === "boolean"
+                ? existingComposioConfig.readOnlyMode
+                : Boolean(config.readOnlyMode);
+            if (options.readOnly !== undefined) {
+                const parsedReadOnly = parseBooleanLike(options.readOnly);
+                if (parsedReadOnly === undefined) {
+                    logger.error("Invalid value for --read-only. Expected one of: true/false/yes/no/1/0.");
+                    return;
+                }
+                readOnlyMode = parsedReadOnly;
+            }
+            if (!options.yes) {
+                const rl = createInterface({ input: process.stdin, output: process.stdout });
+                try {
+                    const apiKeyPrompt = await rl.question(`Composio API key${apiKey ? " [configured]" : ""}: `);
+                    if (apiKeyPrompt.trim())
+                        apiKey = apiKeyPrompt.trim();
+                    const defaultUserPrompt = await rl.question(`Default user ID${defaultUserId ? ` [${defaultUserId}]` : " (optional)"}: `);
+                    if (defaultUserPrompt.trim())
+                        defaultUserId = defaultUserPrompt.trim();
+                    const allowedDefault = allowedToolkits && allowedToolkits.length > 0
+                        ? ` [${allowedToolkits.join(",")}]`
+                        : " (optional)";
+                    const allowedPrompt = await rl.question(`Allowed toolkits${allowedDefault}: `);
+                    if (allowedPrompt.trim()) {
+                        allowedToolkits = parseCsvToolkits(allowedPrompt) || [];
+                    }
+                    const blockedDefault = blockedToolkits && blockedToolkits.length > 0
+                        ? ` [${blockedToolkits.join(",")}]`
+                        : " (optional)";
+                    const blockedPrompt = await rl.question(`Blocked toolkits${blockedDefault}: `);
+                    if (blockedPrompt.trim()) {
+                        blockedToolkits = parseCsvToolkits(blockedPrompt) || [];
+                    }
+                    const readOnlyPrompt = await rl.question(`Enable read-only safety mode? (y/N) [${readOnlyMode ? "Y" : "N"}]: `);
+                    const parsedReadOnlyPrompt = parseBooleanLike(readOnlyPrompt);
+                    if (parsedReadOnlyPrompt !== undefined) {
+                        readOnlyMode = parsedReadOnlyPrompt;
+                    }
+                    else if (readOnlyPrompt.trim()) {
+                        logger.warn("Invalid read-only input. Keeping existing readOnlyMode value.");
+                    }
+                }
+                finally {
+                    rl.close();
+                }
+            }
+            if (!apiKey) {
+                logger.error("Composio API key is required. Provide --api-key or set COMPOSIO_API_KEY.");
+                return;
+            }
+            const mergedComposioConfig = {
+                ...existingComposioConfig,
+                apiKey,
+                readOnlyMode,
+            };
+            if (defaultUserId) {
+                mergedComposioConfig.defaultUserId = defaultUserId;
+            }
+            else {
+                delete mergedComposioConfig.defaultUserId;
+            }
+            if (allowedToolkits && allowedToolkits.length > 0) {
+                mergedComposioConfig.allowedToolkits = allowedToolkits;
+            }
+            else {
+                delete mergedComposioConfig.allowedToolkits;
+            }
+            if (blockedToolkits && blockedToolkits.length > 0) {
+                mergedComposioConfig.blockedToolkits = blockedToolkits;
+            }
+            else {
+                delete mergedComposioConfig.blockedToolkits;
+            }
+            entries.composio = {
+                ...stripLegacyFlatConfigKeys(existingComposioEntry),
+                enabled: true,
+                config: mergedComposioConfig,
+            };
+            plugins.entries = entries;
+            openClawConfig.plugins = plugins;
+            await mkdir(path.dirname(configPath), { recursive: true });
+            await writeFile(configPath, `${JSON.stringify(openClawConfig, null, 2)}\n`, "utf8");
+            console.log("\nComposio setup saved.");
+            console.log("─".repeat(40));
+            console.log(`Config: ${configPath}`);
+            console.log(`defaultUserId: ${defaultUserId || "default"}`);
+            console.log(`readOnlyMode: ${readOnlyMode ? "enabled" : "disabled"}`);
+            if (updatedPluginSystemEnabled) {
+                console.log("plugins.enabled: set to true");
+            }
+            if (addedToAllowlist) {
+                console.log("plugins.allow: added 'composio'");
+            }
+            if (removedFromDenylist) {
+                console.log("plugins.deny: removed 'composio'");
+            }
+            console.log("\nNext steps:");
+            console.log("  1) openclaw gateway restart");
+            console.log("  2) openclaw composio status --user-id <user-id>");
+            console.log();
+        }
+        catch (err) {
+            logger.error(`Failed to run setup: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    });
     // openclaw composio list
     composio
         .command("list")
         .description("List available Composio toolkits")
         .option("-u, --user-id <userId>", "User ID for session scoping")
         .action(async (options) => {
-        if (!config.enabled) {
-            logger.error("Composio plugin is disabled");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
-            const toolkits = await client.listToolkits(options.userId);
+            const toolkits = await composioClient.listToolkits(options.userId);
             console.log("\nAvailable Composio Toolkits:");
             console.log("─".repeat(40));
             for (const toolkit of toolkits.sort()) {
@@ -32,13 +265,13 @@ export function registerComposioCli({ program, client, config, logger }) {
         .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");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
-            const toolkits = toolkit ? [toolkit] : undefined;
-            const statuses = await client.getConnectionStatus(toolkits, options.userId);
+            const toolkitSlug = toolkit ? normalizeToolkitSlug(toolkit) : undefined;
+            const toolkits = toolkitSlug ? [toolkitSlug] : undefined;
+            const statuses = await composioClient.getConnectionStatus(toolkits, options.userId);
             console.log("\nComposio Connection Status:");
             console.log("─".repeat(40));
             if (statuses.length === 0) {
@@ -51,14 +284,14 @@ export function registerComposioCli({ program, client, config, logger }) {
                     console.log(`  ${icon} ${status.toolkit}: ${state}`);
                 }
             }
-            if (toolkit && statuses.length === 1 && !statuses[0]?.connected) {
+            if (toolkitSlug && statuses.length === 1 && !statuses[0]?.connected) {
                 const currentUserId = options.userId || config.defaultUserId || "default";
-                const activeUserIds = await client.findActiveUserIdsForToolkit(toolkit);
+                const activeUserIds = await composioClient.findActiveUserIdsForToolkit(toolkitSlug);
                 const otherUserIds = activeUserIds.filter((uid) => uid !== currentUserId);
                 if (otherUserIds.length > 0) {
-                    console.log(`\n  Hint: '${toolkit}' is connected under other user_id(s): ${otherUserIds.join(", ")}`);
-                    console.log(`  Try: openclaw composio status ${toolkit} --user-id <user-id>`);
-                    console.log(`  Discover accounts: openclaw composio accounts ${toolkit}`);
+                    console.log(`\n  Hint: '${toolkitSlug}' is connected under other user_id(s): ${otherUserIds.join(", ")}`);
+                    console.log(`  Try: openclaw composio status ${toolkitSlug} --user-id <user-id>`);
+                    console.log(`  Discover accounts: openclaw composio accounts ${toolkitSlug}`);
                 }
             }
             console.log();
@@ -74,17 +307,16 @@ export function registerComposioCli({ program, client, config, logger }) {
         .option("-u, --user-id <userId>", "Filter by user ID")
         .option("-s, --statuses <statuses>", "Comma-separated statuses (default: ACTIVE)", "ACTIVE")
         .action(async (toolkit, options) => {
-        if (!config.enabled) {
-            logger.error("Composio plugin is disabled");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
             const statuses = String(options.statuses || "")
                 .split(",")
                 .map(s => s.trim())
                 .filter(Boolean);
-            const accounts = await client.listConnectedAccounts({
-                toolkits: toolkit ? [toolkit] : undefined,
+            const accounts = await composioClient.listConnectedAccounts({
+                toolkits: toolkit ? [normalizeToolkitSlug(toolkit)] : undefined,
                 userIds: options.userId ? [options.userId] : undefined,
                 statuses: statuses.length > 0 ? statuses : ["ACTIVE"],
             });
@@ -110,15 +342,15 @@ export function registerComposioCli({ program, client, config, logger }) {
         .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");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
+            const toolkitSlug = normalizeToolkitSlug(toolkit);
             const currentUserId = options.userId || config.defaultUserId || "default";
-            console.log(`\nInitiating connection to ${toolkit}...`);
+            console.log(`\nInitiating connection to ${toolkitSlug}...`);
             console.log(`Using user_id: ${currentUserId}`);
-            const result = await client.createConnection(toolkit, options.userId);
+            const result = await composioClient.createConnection(toolkitSlug, options.userId);
             if ("error" in result) {
                 logger.error(`Failed to create connection: ${result.error}`);
                 return;
@@ -127,7 +359,7 @@ export function registerComposioCli({ program, client, config, logger }) {
             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 ${toolkit} --user-id ${currentUserId}' to verify.\n`);
+            console.log(`After authentication, run 'openclaw composio status ${toolkitSlug} --user-id ${currentUserId}' to verify.\n`);
             // Try to open URL in browser
             try {
                 const { exec } = await import("node:child_process");
@@ -153,15 +385,15 @@ export function registerComposioCli({ program, client, config, logger }) {
         .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");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
-            console.log(`\nDisconnecting from ${toolkit}...`);
-            const result = await client.disconnectToolkit(toolkit, options.userId);
+            const toolkitSlug = normalizeToolkitSlug(toolkit);
+            console.log(`\nDisconnecting from ${toolkitSlug}...`);
+            const result = await composioClient.disconnectToolkit(toolkitSlug, options.userId);
             if (result.success) {
-                console.log(`Successfully disconnected from ${toolkit}\n`);
+                console.log(`Successfully disconnected from ${toolkitSlug}\n`);
             }
             else {
                 logger.error(`Failed to disconnect: ${result.error}`);
@@ -179,14 +411,13 @@ export function registerComposioCli({ program, client, config, logger }) {
         .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");
+        const composioClient = requireClient();
+        if (!composioClient)
             return;
-        }
         try {
             const limit = parseInt(options.limit, 10) || 10;
-            const toolkits = options.toolkit ? [options.toolkit] : undefined;
-            const results = await client.searchTools(query, {
+            const toolkits = options.toolkit ? [normalizeToolkitSlug(options.toolkit)] : undefined;
+            const results = await composioClient.searchTools(query, {
                 toolkits,
                 limit,
                 userId: options.userId,

package/dist/client.d.ts

@@ -15,12 +15,18 @@ export declare class ComposioClient {
      * Get or create a Tool Router session for a user
      */
     private makeSessionCacheKey;
+    private normalizeConnectedAccountsOverride;
+    private buildToolRouterBlockedToolsConfig;
+    private buildSessionConfig;
     private getSession;
+    private shouldRetrySessionWithoutToolkitFilters;
     private clearUserSessionCache;
     /**
      * Check if a toolkit is allowed based on config
      */
     private isToolkitAllowed;
+    private isLikelyDestructiveToolSlug;
+    private getToolSlugRestrictionError;
     /**
      * Execute a Tool Router meta-tool
      */