@customclaw/composio 0.0.7 → 0.0.8

package/dist/client.js

@@ -1,4 +1,40 @@
 import { Composio } from "@composio/core";
+import { normalizeSessionTags, normalizeToolkitList, normalizeToolkitSlug, normalizeToolSlug, normalizeToolSlugList, } from "./utils.js";
+// Heuristic only: token matching may block some benign tools.
+// Use `allowedToolSlugs` to explicitly override specific slugs.
+const DESTRUCTIVE_TOOL_VERBS = new Set([
+    "CREATE",
+    "DELETE",
+    "DESTROY",
+    "DISABLE",
+    "DISCONNECT",
+    "ERASE",
+    "MODIFY",
+    "PATCH",
+    "POST",
+    "PUT",
+    "REMOVE",
+    "RENAME",
+    "REPLACE",
+    "REVOKE",
+    "SEND",
+    "SET",
+    "TRUNCATE",
+    "UNSUBSCRIBE",
+    "UPDATE",
+    "UPSERT",
+    "WRITE",
+]);
+function isConnectedAccountStatusFilter(value) {
+    return [
+        "INITIALIZING",
+        "INITIATED",
+        "ACTIVE",
+        "FAILED",
+        "EXPIRED",
+        "INACTIVE",
+    ].includes(value);
+}
 /**
  * Composio client wrapper using Tool Router pattern
  */
@@ -10,7 +46,15 @@ export class ComposioClient {
         if (!config.apiKey) {
             throw new Error("Composio API key required. Set COMPOSIO_API_KEY env var or plugins.composio.apiKey in config.");
         }
-        this.config = config;
+        this.config = {
+            ...config,
+            allowedToolkits: normalizeToolkitList(config.allowedToolkits),
+            blockedToolkits: normalizeToolkitList(config.blockedToolkits),
+            sessionTags: normalizeSessionTags(config.sessionTags),
+            allowedToolSlugs: normalizeToolSlugList(config.allowedToolSlugs),
+            blockedToolSlugs: normalizeToolSlugList(config.blockedToolSlugs),
+            readOnlyMode: Boolean(config.readOnlyMode),
+        };
         this.client = new Composio({ apiKey: config.apiKey });
     }
     /**
@@ -27,20 +71,102 @@ export class ComposioClient {
             return `uid:${userId}`;
         }
         const normalized = Object.entries(connectedAccounts)
-            .map(([toolkit, accountId]) => `${toolkit.toLowerCase()}=${accountId}`)
+            .map(([toolkit, accountId]) => `${normalizeToolkitSlug(toolkit)}=${accountId}`)
             .sort()
             .join(",");
         return `uid:${userId}::ca:${normalized}`;
     }
+    normalizeConnectedAccountsOverride(connectedAccounts) {
+        if (!connectedAccounts)
+            return undefined;
+        const normalized = Object.entries(connectedAccounts)
+            .map(([toolkit, accountId]) => [normalizeToolkitSlug(toolkit), String(accountId || "").trim()])
+            .filter(([toolkit, accountId]) => toolkit.length > 0 && accountId.length > 0);
+        if (normalized.length === 0)
+            return undefined;
+        return Object.fromEntries(normalized);
+    }
+    buildToolRouterBlockedToolsConfig() {
+        const blocked = this.config.blockedToolSlugs;
+        if (!blocked || blocked.length === 0)
+            return undefined;
+        const byToolkit = new Map();
+        for (const slug of blocked) {
+            const normalizedSlug = normalizeToolSlug(slug);
+            const toolkit = normalizeToolkitSlug(normalizedSlug.split("_")[0] || "");
+            if (!toolkit)
+                continue;
+            if (!this.isToolkitAllowed(toolkit))
+                continue;
+            if (!byToolkit.has(toolkit))
+                byToolkit.set(toolkit, new Set());
+            byToolkit.get(toolkit).add(normalizedSlug);
+        }
+        if (byToolkit.size === 0)
+            return undefined;
+        const tools = {};
+        for (const [toolkit, slugs] of byToolkit.entries()) {
+            tools[toolkit] = { disable: Array.from(slugs) };
+        }
+        return tools;
+    }
+    buildSessionConfig(connectedAccounts) {
+        const sessionConfig = {};
+        const normalizedConnectedAccounts = this.normalizeConnectedAccountsOverride(connectedAccounts);
+        if (normalizedConnectedAccounts) {
+            sessionConfig.connectedAccounts = normalizedConnectedAccounts;
+        }
+        if (this.config.allowedToolkits && this.config.allowedToolkits.length > 0) {
+            sessionConfig.toolkits = { enable: this.config.allowedToolkits };
+        }
+        else if (this.config.blockedToolkits && this.config.blockedToolkits.length > 0) {
+            sessionConfig.toolkits = { disable: this.config.blockedToolkits };
+        }
+        const tags = new Set(this.config.sessionTags || []);
+        if (this.config.readOnlyMode)
+            tags.add("readOnlyHint");
+        if (tags.size > 0) {
+            sessionConfig.tags = Array.from(tags);
+        }
+        const blockedToolsConfig = this.buildToolRouterBlockedToolsConfig();
+        if (blockedToolsConfig) {
+            sessionConfig.tools = blockedToolsConfig;
+        }
+        return Object.keys(sessionConfig).length > 0 ? sessionConfig : undefined;
+    }
     async getSession(userId, connectedAccounts) {
-        const key = this.makeSessionCacheKey(userId, connectedAccounts);
+        const normalizedConnectedAccounts = this.normalizeConnectedAccountsOverride(connectedAccounts);
+        const key = this.makeSessionCacheKey(userId, normalizedConnectedAccounts);
         if (this.sessionCache.has(key)) {
             return this.sessionCache.get(key);
         }
-        const session = await this.client.toolRouter.create(userId, connectedAccounts ? { connectedAccounts } : undefined);
+        const sessionConfig = this.buildSessionConfig(normalizedConnectedAccounts);
+        let session;
+        try {
+            session = await this.client.toolRouter.create(userId, sessionConfig);
+        }
+        catch (err) {
+            if (!this.shouldRetrySessionWithoutToolkitFilters(err, sessionConfig)) {
+                throw err;
+            }
+            const { toolkits: _removedToolkits, ...retryWithoutToolkits } = sessionConfig ?? {};
+            const retryConfig = Object.keys(retryWithoutToolkits).length > 0
+                ? retryWithoutToolkits
+                : undefined;
+            session = await this.client.toolRouter.create(userId, retryConfig);
+        }
         this.sessionCache.set(key, session);
         return session;
     }
+    shouldRetrySessionWithoutToolkitFilters(err, sessionConfig) {
+        const enabledToolkits = sessionConfig?.toolkits?.enable;
+        if (!Array.isArray(enabledToolkits) || enabledToolkits.length === 0) {
+            return false;
+        }
+        const message = String(err instanceof Error ? err.message : err || "").toLowerCase();
+        return (message.includes("require auth configs but none exist") &&
+            message.includes("please specify them in auth_configs"));
+    }
     clearUserSessionCache(userId) {
         const prefix = `uid:${userId}`;
         for (const key of this.sessionCache.keys()) {
@@ -53,23 +179,56 @@ export class ComposioClient {
      * Check if a toolkit is allowed based on config
      */
     isToolkitAllowed(toolkit) {
+        const normalizedToolkit = normalizeToolkitSlug(toolkit);
+        if (!normalizedToolkit)
+            return false;
         const { allowedToolkits, blockedToolkits } = this.config;
-        if (blockedToolkits?.includes(toolkit.toLowerCase())) {
+        if (blockedToolkits?.includes(normalizedToolkit)) {
             return false;
         }
         if (allowedToolkits && allowedToolkits.length > 0) {
-            return allowedToolkits.includes(toolkit.toLowerCase());
+            return allowedToolkits.includes(normalizedToolkit);
         }
         return true;
     }
+    isLikelyDestructiveToolSlug(toolSlug) {
+        const tokens = normalizeToolSlug(toolSlug)
+            .split("_")
+            .filter(Boolean);
+        return tokens.some((token) => DESTRUCTIVE_TOOL_VERBS.has(token));
+    }
+    getToolSlugRestrictionError(toolSlug) {
+        const normalizedToolSlug = normalizeToolSlug(toolSlug);
+        if (!normalizedToolSlug)
+            return "tool_slug is required";
+        const isExplicitlyAllowed = this.config.allowedToolSlugs?.includes(normalizedToolSlug) ?? false;
+        if (this.config.allowedToolSlugs && this.config.allowedToolSlugs.length > 0) {
+            if (!isExplicitlyAllowed) {
+                return `Tool '${normalizedToolSlug}' is not in allowedToolSlugs`;
+            }
+        }
+        if (this.config.blockedToolSlugs?.includes(normalizedToolSlug)) {
+            return `Tool '${normalizedToolSlug}' is blocked by plugin configuration`;
+        }
+        if (this.config.readOnlyMode && !isExplicitlyAllowed && this.isLikelyDestructiveToolSlug(normalizedToolSlug)) {
+            return (`Tool '${normalizedToolSlug}' was blocked by readOnlyMode because it appears to modify data. ` +
+                "Disable readOnlyMode or add this slug to allowedToolSlugs if execution is intentional.");
+        }
+        return undefined;
+    }
     /**
      * Execute a Tool Router meta-tool
      */
-    async executeMetaTool(toolName, args) {
-        const response = await this.client.client.tools.execute(toolName, {
+    async executeMetaTool(sessionId, toolName, args) {
+        const response = await this.client.tools.executeMetaTool(toolName, {
+            sessionId,
             arguments: args,
         });
-        return response;
+        return {
+            successful: Boolean(response.successful),
+            data: response.data,
+            error: response.error ?? undefined,
+        };
     }
     /**
      * Search for tools matching a query using COMPOSIO_SEARCH_TOOLS
@@ -77,10 +236,10 @@ export class ComposioClient {
     async searchTools(query, options) {
         const userId = this.getUserId(options?.userId);
         const session = await this.getSession(userId);
+        const requestedToolkits = normalizeToolkitList(options?.toolkits);
         try {
-            const response = await this.executeMetaTool("COMPOSIO_SEARCH_TOOLS", {
+            const response = await this.executeMetaTool(session.sessionId, "COMPOSIO_SEARCH_TOOLS", {
                 queries: [{ use_case: query }],
-                session: { id: session.sessionId },
             });
             if (!response.successful || !response.data) {
                 throw new Error(response.error || "Search failed");
@@ -100,11 +259,11 @@ export class ComposioClient {
                         continue;
                     seenSlugs.add(slug);
                     const schema = toolSchemas[slug];
-                    const toolkit = schema?.toolkit || slug.split("_")[0] || "";
+                    const toolkit = normalizeToolkitSlug(schema?.toolkit || slug.split("_")[0] || "");
                     if (!this.isToolkitAllowed(toolkit))
                         continue;
-                    if (options?.toolkits && options.toolkits.length > 0) {
-                        if (!options.toolkits.some(t => t.toLowerCase() === toolkit.toLowerCase())) {
+                    if (requestedToolkits && requestedToolkits.length > 0) {
+                        if (!requestedToolkits.includes(toolkit)) {
                             continue;
                         }
                     }
@@ -132,7 +291,12 @@ export class ComposioClient {
      */
     async executeTool(toolSlug, args, userId, connectedAccountId) {
         const uid = this.getUserId(userId);
-        const toolkit = toolSlug.split("_")[0]?.toLowerCase() || "";
+        const normalizedToolSlug = normalizeToolSlug(toolSlug);
+        const toolRestrictionError = this.getToolSlugRestrictionError(normalizedToolSlug);
+        if (toolRestrictionError) {
+            return { success: false, error: toolRestrictionError };
+        }
+        const toolkit = normalizeToolkitSlug(normalizedToolSlug.split("_")[0] || "");
         if (!this.isToolkitAllowed(toolkit)) {
             return {
                 success: false,
@@ -151,15 +315,14 @@ export class ComposioClient {
             ? { [toolkit]: accountResolution.connectedAccountId }
             : undefined);
         try {
-            const response = await this.executeMetaTool("COMPOSIO_MULTI_EXECUTE_TOOL", {
-                tools: [{ tool_slug: toolSlug, arguments: args }],
-                session: { id: session.sessionId },
+            const response = await this.executeMetaTool(session.sessionId, "COMPOSIO_MULTI_EXECUTE_TOOL", {
+                tools: [{ tool_slug: normalizedToolSlug, arguments: args }],
                 sync_response_to_workbench: false,
             });
             if (!response.successful) {
                 const recovered = await this.tryExecutionRecovery({
                     uid,
-                    toolSlug,
+                    toolSlug: normalizedToolSlug,
                     args,
                     connectedAccountId: accountResolution.connectedAccountId,
                     metaError: response.error,
@@ -179,7 +342,7 @@ export class ComposioClient {
             if (!toolResponse.successful) {
                 const recovered = await this.tryExecutionRecovery({
                     uid,
-                    toolSlug,
+                    toolSlug: normalizedToolSlug,
                     args,
                     connectedAccountId: accountResolution.connectedAccountId,
                     metaError: toolResponse.error ?? undefined,
@@ -315,12 +478,13 @@ export class ComposioClient {
         return String(first?.error || "");
     }
     async resolveConnectedAccountForExecution(params) {
-        const { toolkit, userId } = params;
+        const toolkit = normalizeToolkitSlug(params.toolkit);
+        const { userId } = params;
         const explicitId = params.connectedAccountId?.trim();
         if (explicitId) {
             try {
                 const account = await this.client.connectedAccounts.get(explicitId);
-                const accountToolkit = String(account?.toolkit?.slug || "").toLowerCase();
+                const accountToolkit = normalizeToolkitSlug(String(account?.toolkit?.slug || ""));
                 const accountStatus = String(account?.status || "").toUpperCase();
                 if (accountToolkit && accountToolkit !== toolkit) {
                     return {
@@ -361,14 +525,15 @@ export class ComposioClient {
         const uid = this.getUserId(userId);
         const session = await this.getSession(uid);
         try {
-            if (toolkits && toolkits.length > 0) {
-                const requestedToolkits = toolkits.filter(t => this.isToolkitAllowed(t));
+            const normalizedToolkits = normalizeToolkitList(toolkits);
+            if (normalizedToolkits && normalizedToolkits.length > 0) {
+                const requestedToolkits = normalizedToolkits.filter((t) => this.isToolkitAllowed(t));
                 if (requestedToolkits.length === 0)
                     return [];
                 const toolkitStateMap = await this.getToolkitStateMap(session, requestedToolkits);
                 const activeAccountToolkits = await this.getActiveConnectedAccountToolkits(uid, requestedToolkits);
                 return requestedToolkits.map((toolkit) => {
-                    const key = toolkit.toLowerCase();
+                    const key = normalizeToolkitSlug(toolkit);
                     return {
                         toolkit,
                         connected: (toolkitStateMap.get(key) ?? false) || activeAccountToolkits.has(key),
@@ -413,7 +578,7 @@ export class ComposioClient {
             });
             const items = response.items || [];
             for (const tk of items) {
-                const key = tk.slug.toLowerCase();
+                const key = normalizeToolkitSlug(tk.slug);
                 const isActive = tk.connection?.isActive ?? false;
                 map.set(key, (map.get(key) ?? false) || isActive);
             }
@@ -428,6 +593,7 @@ export class ComposioClient {
     }
     async getActiveConnectedAccountToolkits(userId, toolkits) {
         const connected = new Set();
+        const normalizedToolkits = normalizeToolkitList(toolkits);
         let cursor;
         const seenCursors = new Set();
         try {
@@ -435,7 +601,7 @@ export class ComposioClient {
                 const response = await this.client.connectedAccounts.list({
                     userIds: [userId],
                     statuses: ["ACTIVE"],
-                    ...(toolkits && toolkits.length > 0 ? { toolkitSlugs: toolkits } : {}),
+                    ...(normalizedToolkits && normalizedToolkits.length > 0 ? { toolkitSlugs: normalizedToolkits } : {}),
                     limit: 100,
                     ...(cursor ? { cursor } : {}),
                 });
@@ -443,12 +609,12 @@ export class ComposioClient {
                     ? response
                     : response?.items || []);
                 for (const item of items) {
-                    const slug = item.toolkit?.slug;
+                    const slug = normalizeToolkitSlug(item.toolkit?.slug || "");
                     if (!slug)
                         continue;
                     if (item.status && String(item.status).toUpperCase() !== "ACTIVE")
                         continue;
-                    connected.add(slug.toLowerCase());
+                    connected.add(slug);
                 }
                 cursor = Array.isArray(response)
                     ? null
@@ -469,10 +635,9 @@ export class ComposioClient {
     normalizeStatuses(statuses) {
         if (!statuses || statuses.length === 0)
             return undefined;
-        const allowed = new Set(["INITIALIZING", "INITIATED", "ACTIVE", "FAILED", "EXPIRED", "INACTIVE"]);
         const normalized = statuses
             .map(s => String(s || "").trim().toUpperCase())
-            .filter(s => allowed.has(s));
+            .filter(isConnectedAccountStatusFilter);
         return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
     }
     /**
@@ -480,9 +645,7 @@ export class ComposioClient {
      * Uses raw API first to preserve user_id in responses, then falls back to SDK-normalized output.
      */
     async listConnectedAccounts(options) {
-        const toolkits = options?.toolkits
-            ?.map(t => String(t || "").trim())
-            .filter(t => t.length > 0 && this.isToolkitAllowed(t));
+        const toolkits = normalizeToolkitList(options?.toolkits)?.filter((t) => this.isToolkitAllowed(t));
         const userIds = options?.userIds
             ?.map(u => String(u || "").trim())
             .filter(Boolean);
@@ -508,10 +671,11 @@ export class ComposioClient {
      * Find user IDs that have an active connected account for a toolkit.
      */
     async findActiveUserIdsForToolkit(toolkit) {
-        if (!this.isToolkitAllowed(toolkit))
+        const normalizedToolkit = normalizeToolkitSlug(toolkit);
+        if (!this.isToolkitAllowed(normalizedToolkit))
             return [];
         const accounts = await this.listConnectedAccounts({
-            toolkits: [toolkit],
+            toolkits: [normalizedToolkit],
             statuses: ["ACTIVE"],
         });
         const userIds = new Set();
@@ -537,7 +701,7 @@ export class ComposioClient {
                 ? response
                 : response?.items || []);
             for (const item of items) {
-                const toolkitSlug = (item.toolkit?.slug || "").toString().toLowerCase();
+                const toolkitSlug = normalizeToolkitSlug((item.toolkit?.slug || "").toString());
                 if (!toolkitSlug)
                     continue;
                 if (!this.isToolkitAllowed(toolkitSlug))
@@ -582,7 +746,7 @@ export class ComposioClient {
                 ? response
                 : response?.items || []);
             for (const item of items) {
-                const toolkitSlug = (item.toolkit?.slug || "").toString().toLowerCase();
+                const toolkitSlug = normalizeToolkitSlug((item.toolkit?.slug || "").toString());
                 if (!toolkitSlug)
                     continue;
                 if (!this.isToolkitAllowed(toolkitSlug))
@@ -615,12 +779,16 @@ export class ComposioClient {
      */
     async createConnection(toolkit, userId) {
         const uid = this.getUserId(userId);
-        if (!this.isToolkitAllowed(toolkit)) {
-            return { error: `Toolkit '${toolkit}' is not allowed by plugin configuration` };
+        const toolkitSlug = normalizeToolkitSlug(toolkit);
+        if (!toolkitSlug) {
+            return { error: "Toolkit is required" };
+        }
+        if (!this.isToolkitAllowed(toolkitSlug)) {
+            return { error: `Toolkit '${toolkitSlug}' is not allowed by plugin configuration` };
         }
         try {
             const session = await this.getSession(uid);
-            const result = await session.authorize(toolkit);
+            const result = await session.authorize(toolkitSlug);
             return { authUrl: result.redirectUrl || result.url || "" };
         }
         catch (err) {
@@ -646,7 +814,7 @@ export class ComposioClient {
                 });
                 const allToolkits = response.items || [];
                 for (const tk of allToolkits) {
-                    const slug = tk.slug.toLowerCase();
+                    const slug = normalizeToolkitSlug(tk.slug);
                     if (!this.isToolkitAllowed(slug))
                         continue;
                     seen.add(slug);
@@ -674,24 +842,34 @@ export class ComposioClient {
      */
     async disconnectToolkit(toolkit, userId) {
         const uid = this.getUserId(userId);
+        const toolkitSlug = normalizeToolkitSlug(toolkit);
+        if (!toolkitSlug) {
+            return { success: false, error: "Toolkit is required" };
+        }
+        if (this.config.readOnlyMode) {
+            return {
+                success: false,
+                error: "Disconnect is blocked by readOnlyMode.",
+            };
+        }
         try {
             const activeAccounts = await this.listConnectedAccounts({
-                toolkits: [toolkit],
+                toolkits: [toolkitSlug],
                 userIds: [uid],
                 statuses: ["ACTIVE"],
             });
             if (activeAccounts.length === 0) {
-                return { success: false, error: `No connection found for toolkit '${toolkit}'` };
+                return { success: false, error: `No connection found for toolkit '${toolkitSlug}'` };
             }
             if (activeAccounts.length > 1) {
                 const ids = activeAccounts.map(a => a.id).join(", ");
                 return {
                     success: false,
-                    error: `Multiple ACTIVE '${toolkit}' accounts found for user_id '${uid}': ${ids}. ` +
+                    error: `Multiple ACTIVE '${toolkitSlug}' accounts found for user_id '${uid}': ${ids}. ` +
                         "Use the dashboard to disconnect a specific account.",
                 };
             }
-            await this.client.connectedAccounts.delete({ connectedAccountId: activeAccounts[0].id });
+            await this.client.connectedAccounts.delete(activeAccounts[0].id);
             // Clear session cache to refresh connection status
             this.clearUserSessionCache(uid);
             return { success: true };

package/dist/config.d.ts

@@ -9,6 +9,15 @@ export declare const ComposioConfigSchema: z.ZodObject<{
     defaultUserId: z.ZodOptional<z.ZodString>;
     allowedToolkits: z.ZodOptional<z.ZodArray<z.ZodString>>;
     blockedToolkits: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    readOnlyMode: z.ZodDefault<z.ZodBoolean>;
+    sessionTags: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+        readOnlyHint: "readOnlyHint";
+        destructiveHint: "destructiveHint";
+        idempotentHint: "idempotentHint";
+        openWorldHint: "openWorldHint";
+    }>>>;
+    allowedToolSlugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    blockedToolSlugs: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 /**
  * Parse and validate plugin config with environment fallbacks
@@ -41,6 +50,26 @@ export declare const composioConfigUiHints: {
         help: string;
         advanced: boolean;
     };
+    readOnlyMode: {
+        label: string;
+        help: string;
+        advanced: boolean;
+    };
+    sessionTags: {
+        label: string;
+        help: string;
+        advanced: boolean;
+    };
+    allowedToolSlugs: {
+        label: string;
+        help: string;
+        advanced: boolean;
+    };
+    blockedToolSlugs: {
+        label: string;
+        help: string;
+        advanced: boolean;
+    };
 };
 /**
  * Plugin config schema object for openclaw
@@ -71,5 +100,25 @@ export declare const composioPluginConfigSchema: {
             help: string;
             advanced: boolean;
         };
+        readOnlyMode: {
+            label: string;
+            help: string;
+            advanced: boolean;
+        };
+        sessionTags: {
+            label: string;
+            help: string;
+            advanced: boolean;
+        };
+        allowedToolSlugs: {
+            label: string;
+            help: string;
+            advanced: boolean;
+        };
+        blockedToolSlugs: {
+            label: string;
+            help: string;
+            advanced: boolean;
+        };
     };
 };

package/dist/config.js

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { LEGACY_ENTRY_FLAT_CONFIG_KEYS, LEGACY_SHAPE_ERROR, SESSION_TAGS, isRecord, normalizeSessionTags, normalizeToolkitList, normalizeToolSlugList, } from "./utils.js";
 /**
  * Zod schema for Composio plugin configuration
  */
@@ -8,36 +9,39 @@ export const ComposioConfigSchema = z.object({
     defaultUserId: z.string().optional(),
     allowedToolkits: z.array(z.string()).optional(),
     blockedToolkits: z.array(z.string()).optional(),
+    readOnlyMode: z.boolean().default(false),
+    sessionTags: z.array(z.enum(SESSION_TAGS)).optional(),
+    allowedToolSlugs: z.array(z.string()).optional(),
+    blockedToolSlugs: z.array(z.string()).optional(),
 });
 /**
  * Parse and validate plugin config with environment fallbacks
  */
 export function parseComposioConfig(value) {
-    const raw = value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : {};
-    // Support both plugin entry shape ({ enabled, config: {...} }) and flat shape.
-    const configObj = raw.config;
-    const enabled = (typeof raw.enabled === "boolean" ? raw.enabled : undefined) ??
-        (typeof configObj?.enabled === "boolean" ? configObj.enabled : undefined) ??
-        true;
-    const defaultUserId = (typeof raw.defaultUserId === "string" ? raw.defaultUserId : undefined) ??
-        (typeof configObj?.defaultUserId === "string" ? configObj.defaultUserId : undefined);
-    const allowedToolkits = (Array.isArray(raw.allowedToolkits) ? raw.allowedToolkits : undefined) ??
-        (Array.isArray(configObj?.allowedToolkits) ? configObj.allowedToolkits : undefined);
-    const blockedToolkits = (Array.isArray(raw.blockedToolkits) ? raw.blockedToolkits : undefined) ??
-        (Array.isArray(configObj?.blockedToolkits) ? configObj.blockedToolkits : undefined);
-    // Allow API key from config.apiKey, top-level apiKey, or environment.
-    const apiKey = (typeof configObj?.apiKey === "string" && configObj.apiKey.trim()) ||
-        (typeof raw.apiKey === "string" && raw.apiKey.trim()) ||
+    const raw = isRecord(value) ? value : {};
+    const configObj = isRecord(raw.config) ? raw.config : undefined;
+    if (configObj) {
+        const hasLegacyFlatKeys = LEGACY_ENTRY_FLAT_CONFIG_KEYS.some((key) => key in raw);
+        if (hasLegacyFlatKeys) {
+            throw new Error(LEGACY_SHAPE_ERROR);
+        }
+    }
+    const source = configObj ?? raw;
+    const enabled = typeof raw.enabled === "boolean" ? raw.enabled : true;
+    const readOnlyMode = typeof source.readOnlyMode === "boolean" ? source.readOnlyMode : false;
+    const apiKey = (typeof source.apiKey === "string" && source.apiKey.trim()) ||
         process.env.COMPOSIO_API_KEY ||
         "";
     return ComposioConfigSchema.parse({
         enabled,
         apiKey,
-        defaultUserId,
-        allowedToolkits,
-        blockedToolkits,
+        defaultUserId: typeof source.defaultUserId === "string" ? source.defaultUserId : undefined,
+        allowedToolkits: normalizeToolkitList(Array.isArray(source.allowedToolkits) ? source.allowedToolkits : undefined),
+        blockedToolkits: normalizeToolkitList(Array.isArray(source.blockedToolkits) ? source.blockedToolkits : undefined),
+        readOnlyMode,
+        sessionTags: normalizeSessionTags(Array.isArray(source.sessionTags) ? source.sessionTags : undefined),
+        allowedToolSlugs: normalizeToolSlugList(Array.isArray(source.allowedToolSlugs) ? source.allowedToolSlugs : undefined),
+        blockedToolSlugs: normalizeToolSlugList(Array.isArray(source.blockedToolSlugs) ? source.blockedToolSlugs : undefined),
     });
 }
 /**
@@ -67,6 +71,26 @@ export const composioConfigUiHints = {
         help: "Block specific toolkits from being used",
         advanced: true,
     },
+    readOnlyMode: {
+        label: "Read-Only Mode",
+        help: "Block likely-destructive tool actions by token matching; allow specific slugs with allowedToolSlugs if needed",
+        advanced: true,
+    },
+    sessionTags: {
+        label: "Session Tags",
+        help: "Composio Tool Router behavior tags (e.g., readOnlyHint, destructiveHint)",
+        advanced: true,
+    },
+    allowedToolSlugs: {
+        label: "Allowed Tool Slugs",
+        help: "Optional explicit allowlist for tool slugs (UPPERCASE)",
+        advanced: true,
+    },
+    blockedToolSlugs: {
+        label: "Blocked Tool Slugs",
+        help: "Explicit denylist for tool slugs (UPPERCASE)",
+        advanced: true,
+    },
 };
 /**
  * Plugin config schema object for openclaw

package/dist/index.d.ts

@@ -49,6 +49,26 @@ declare const composioPlugin: {
                 help: string;
                 advanced: boolean;
             };
+            readOnlyMode: {
+                label: string;
+                help: string;
+                advanced: boolean;
+            };
+            sessionTags: {
+                label: string;
+                help: string;
+                advanced: boolean;
+            };
+            allowedToolSlugs: {
+                label: string;
+                help: string;
+                advanced: boolean;
+            };
+            blockedToolSlugs: {
+                label: string;
+                help: string;
+                advanced: boolean;
+            };
         };
     };
     register(api: any): void;