@customclaw/composio 0.0.6 → 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 });
     }
     /**
@@ -22,35 +66,169 @@ export class ComposioClient {
     /**
      * Get or create a Tool Router session for a user
      */
-    async getSession(userId) {
-        if (this.sessionCache.has(userId)) {
-            return this.sessionCache.get(userId);
+    makeSessionCacheKey(userId, connectedAccounts) {
+        if (!connectedAccounts || Object.keys(connectedAccounts).length === 0) {
+            return `uid:${userId}`;
+        }
+        const normalized = Object.entries(connectedAccounts)
+            .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 normalizedConnectedAccounts = this.normalizeConnectedAccountsOverride(connectedAccounts);
+        const key = this.makeSessionCacheKey(userId, normalizedConnectedAccounts);
+        if (this.sessionCache.has(key)) {
+            return this.sessionCache.get(key);
+        }
+        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);
         }
-        const session = await this.client.toolRouter.create(userId);
-        this.sessionCache.set(userId, session);
+        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()) {
+            if (!key.startsWith(prefix))
+                continue;
+            this.sessionCache.delete(key);
+        }
+    }
     /**
      * 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
@@ -58,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");
@@ -81,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;
                         }
                     }
@@ -111,23 +289,47 @@ export class ComposioClient {
     /**
      * Execute a single tool using COMPOSIO_MULTI_EXECUTE_TOOL
      */
-    async executeTool(toolSlug, args, userId) {
+    async executeTool(toolSlug, args, userId, connectedAccountId) {
         const uid = this.getUserId(userId);
-        const session = await this.getSession(uid);
-        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,
                 error: `Toolkit '${toolkit}' is not allowed by plugin configuration`,
             };
         }
+        const accountResolution = await this.resolveConnectedAccountForExecution({
+            toolkit,
+            userId: uid,
+            connectedAccountId,
+        });
+        if ("error" in accountResolution) {
+            return { success: false, error: accountResolution.error };
+        }
+        const session = await this.getSession(uid, accountResolution.connectedAccountId
+            ? { [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: normalizedToolSlug,
+                    args,
+                    connectedAccountId: accountResolution.connectedAccountId,
+                    metaError: response.error,
+                    metaData: response.data,
+                });
+                if (recovered)
+                    return recovered;
                 return { success: false, error: response.error || "Execution failed" };
             }
             const results = response.data?.results || [];
@@ -137,6 +339,18 @@ export class ComposioClient {
             }
             // Response data is nested under result.response
             const toolResponse = result.response;
+            if (!toolResponse.successful) {
+                const recovered = await this.tryExecutionRecovery({
+                    uid,
+                    toolSlug: normalizedToolSlug,
+                    args,
+                    connectedAccountId: accountResolution.connectedAccountId,
+                    metaError: toolResponse.error ?? undefined,
+                    metaData: response.data,
+                });
+                if (recovered)
+                    return recovered;
+            }
             return {
                 success: toolResponse.successful,
                 data: toolResponse.data,
@@ -150,6 +364,160 @@ export class ComposioClient {
             };
         }
     }
+    async tryExecutionRecovery(params) {
+        const directFallback = await this.tryDirectExecutionFallback(params);
+        if (directFallback?.success)
+            return directFallback;
+        const hintedRetry = await this.tryHintedIdentifierRetry({
+            ...params,
+            additionalError: directFallback?.error,
+        });
+        if (hintedRetry)
+            return hintedRetry;
+        return directFallback;
+    }
+    async tryDirectExecutionFallback(params) {
+        if (!this.shouldFallbackToDirectExecution(params.uid, params.metaError, params.metaData)) {
+            return null;
+        }
+        return this.executeDirectTool(params.toolSlug, params.uid, params.args, params.connectedAccountId);
+    }
+    async executeDirectTool(toolSlug, userId, args, connectedAccountId) {
+        try {
+            const response = await this.client.tools.execute(toolSlug, {
+                userId,
+                connectedAccountId,
+                arguments: args,
+                dangerouslySkipVersionCheck: true,
+            });
+            return {
+                success: Boolean(response?.successful),
+                data: response?.data,
+                error: response?.error ?? undefined,
+            };
+        }
+        catch (err) {
+            return {
+                success: false,
+                error: err instanceof Error ? err.message : String(err),
+            };
+        }
+    }
+    async tryHintedIdentifierRetry(params) {
+        const combined = this.buildCombinedErrorText(params.metaError, params.metaData, params.additionalError);
+        if (!this.shouldRetryFromServerHint(combined))
+            return null;
+        const hint = this.extractServerHintLiteral(combined);
+        if (!hint)
+            return null;
+        const retryArgs = this.buildRetryArgsFromHint(params.args, combined, hint);
+        if (!retryArgs)
+            return null;
+        return this.executeDirectTool(params.toolSlug, params.uid, retryArgs, params.connectedAccountId);
+    }
+    shouldFallbackToDirectExecution(uid, metaError, metaData) {
+        if (uid === "default")
+            return false;
+        const combined = this.buildCombinedErrorText(metaError, metaData).toLowerCase();
+        return combined.includes("no connected account found for entity id default");
+    }
+    shouldRetryFromServerHint(errorText) {
+        const lower = errorText.toLowerCase();
+        return (lower.includes("only allowed to access") ||
+            lower.includes("allowed to access the"));
+    }
+    extractServerHintLiteral(errorText) {
+        const matches = errorText.match(/`([^`]+)`/);
+        if (!matches?.[1])
+            return undefined;
+        const literal = matches[1].trim();
+        if (!literal)
+            return undefined;
+        if (literal.length > 64)
+            return undefined;
+        if (/\s/.test(literal))
+            return undefined;
+        return literal;
+    }
+    buildRetryArgsFromHint(args, errorText, hint) {
+        const stringEntries = Object.entries(args).filter(([, value]) => typeof value === "string");
+        if (stringEntries.length === 1) {
+            const [field, current] = stringEntries[0];
+            if (current === hint)
+                return null;
+            return { ...args, [field]: hint };
+        }
+        if (stringEntries.length === 0) {
+            const missing = this.extractSingleMissingField(errorText);
+            if (!missing)
+                return null;
+            return { ...args, [missing]: hint };
+        }
+        return null;
+    }
+    extractSingleMissingField(errorText) {
+        const match = errorText.match(/following fields are missing:\s*\{([^}]+)\}/i);
+        const raw = match?.[1];
+        if (!raw)
+            return undefined;
+        const fields = raw
+            .split(",")
+            .map(part => part.trim().replace(/^['"]|['"]$/g, ""))
+            .filter(Boolean);
+        return fields.length === 1 ? fields[0] : undefined;
+    }
+    buildCombinedErrorText(metaError, metaData, additionalError) {
+        return [metaError, this.extractNestedMetaError(metaData), additionalError]
+            .map(v => String(v || "").trim())
+            .filter(Boolean)
+            .join("\n");
+    }
+    extractNestedMetaError(metaData) {
+        const results = metaData?.results || [];
+        const first = results[0];
+        return String(first?.error || "");
+    }
+    async resolveConnectedAccountForExecution(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 = normalizeToolkitSlug(String(account?.toolkit?.slug || ""));
+                const accountStatus = String(account?.status || "").toUpperCase();
+                if (accountToolkit && accountToolkit !== toolkit) {
+                    return {
+                        error: `Connected account '${explicitId}' belongs to toolkit '${accountToolkit}', but tool '${toolkit}' was requested.`,
+                    };
+                }
+                if (accountStatus && accountStatus !== "ACTIVE") {
+                    return {
+                        error: `Connected account '${explicitId}' is '${accountStatus}', not ACTIVE.`,
+                    };
+                }
+                return { connectedAccountId: explicitId };
+            }
+            catch (err) {
+                return {
+                    error: `Invalid connected_account_id '${explicitId}': ${err instanceof Error ? err.message : String(err)}`,
+                };
+            }
+        }
+        const activeAccounts = await this.listConnectedAccounts({
+            toolkits: [toolkit],
+            userIds: [userId],
+            statuses: ["ACTIVE"],
+        });
+        if (activeAccounts.length <= 1) {
+            return { connectedAccountId: activeAccounts[0]?.id };
+        }
+        const ids = activeAccounts.map(a => a.id).join(", ");
+        return {
+            error: `Multiple ACTIVE '${toolkit}' accounts found for user_id '${userId}': ${ids}. ` +
+                "Please provide connected_account_id to choose one explicitly.",
+        };
+    }
     /**
      * Get connection status for toolkits using session.toolkits()
      */
@@ -157,53 +525,270 @@ export class ComposioClient {
         const uid = this.getUserId(userId);
         const session = await this.getSession(uid);
         try {
-            const response = await session.toolkits();
-            const allToolkits = response.items || [];
-            const statuses = [];
-            if (toolkits && toolkits.length > 0) {
-                // Check specific toolkits
-                for (const toolkit of toolkits) {
-                    if (!this.isToolkitAllowed(toolkit))
-                        continue;
-                    const found = allToolkits.find(t => t.slug.toLowerCase() === toolkit.toLowerCase());
-                    statuses.push({
+            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 = normalizeToolkitSlug(toolkit);
+                    return {
                         toolkit,
-                        connected: found?.connection?.isActive ?? false,
+                        connected: (toolkitStateMap.get(key) ?? false) || activeAccountToolkits.has(key),
                         userId: uid,
-                    });
-                }
+                    };
+                });
             }
-            else {
-                // Return all connected toolkits
-                for (const tk of allToolkits) {
-                    if (!this.isToolkitAllowed(tk.slug))
-                        continue;
-                    if (!tk.connection?.isActive)
-                        continue;
-                    statuses.push({
-                        toolkit: tk.slug,
-                        connected: true,
-                        userId: uid,
-                    });
-                }
+            const toolkitStateMap = await this.getToolkitStateMap(session);
+            const activeAccountToolkits = await this.getActiveConnectedAccountToolkits(uid);
+            const connected = new Set();
+            for (const [slug, isActive] of toolkitStateMap.entries()) {
+                if (!isActive)
+                    continue;
+                if (!this.isToolkitAllowed(slug))
+                    continue;
+                connected.add(slug);
             }
-            return statuses;
+            for (const slug of activeAccountToolkits) {
+                if (!this.isToolkitAllowed(slug))
+                    continue;
+                connected.add(slug);
+            }
+            return Array.from(connected).map((toolkit) => ({
+                toolkit,
+                connected: true,
+                userId: uid,
+            }));
         }
         catch (err) {
             throw new Error(`Failed to get connection status: ${err instanceof Error ? err.message : String(err)}`);
         }
     }
+    async getToolkitStateMap(session, toolkits) {
+        const map = new Map();
+        let nextCursor;
+        const seenCursors = new Set();
+        do {
+            const response = await session.toolkits({
+                nextCursor,
+                limit: 100,
+                ...(toolkits && toolkits.length > 0 ? { toolkits } : { isConnected: true }),
+            });
+            const items = response.items || [];
+            for (const tk of items) {
+                const key = normalizeToolkitSlug(tk.slug);
+                const isActive = tk.connection?.isActive ?? false;
+                map.set(key, (map.get(key) ?? false) || isActive);
+            }
+            nextCursor = response.nextCursor;
+            if (!nextCursor)
+                break;
+            if (seenCursors.has(nextCursor))
+                break;
+            seenCursors.add(nextCursor);
+        } while (true);
+        return map;
+    }
+    async getActiveConnectedAccountToolkits(userId, toolkits) {
+        const connected = new Set();
+        const normalizedToolkits = normalizeToolkitList(toolkits);
+        let cursor;
+        const seenCursors = new Set();
+        try {
+            do {
+                const response = await this.client.connectedAccounts.list({
+                    userIds: [userId],
+                    statuses: ["ACTIVE"],
+                    ...(normalizedToolkits && normalizedToolkits.length > 0 ? { toolkitSlugs: normalizedToolkits } : {}),
+                    limit: 100,
+                    ...(cursor ? { cursor } : {}),
+                });
+                const items = (Array.isArray(response)
+                    ? response
+                    : response?.items || []);
+                for (const item of items) {
+                    const slug = normalizeToolkitSlug(item.toolkit?.slug || "");
+                    if (!slug)
+                        continue;
+                    if (item.status && String(item.status).toUpperCase() !== "ACTIVE")
+                        continue;
+                    connected.add(slug);
+                }
+                cursor = Array.isArray(response)
+                    ? null
+                    : (response?.nextCursor ?? null);
+                if (!cursor)
+                    break;
+                if (seenCursors.has(cursor))
+                    break;
+                seenCursors.add(cursor);
+            } while (true);
+            return connected;
+        }
+        catch {
+            // Best-effort fallback: preserve status checks based on session.toolkits only.
+            return connected;
+        }
+    }
+    normalizeStatuses(statuses) {
+        if (!statuses || statuses.length === 0)
+            return undefined;
+        const normalized = statuses
+            .map(s => String(s || "").trim().toUpperCase())
+            .filter(isConnectedAccountStatusFilter);
+        return normalized.length > 0 ? Array.from(new Set(normalized)) : undefined;
+    }
+    /**
+     * List connected accounts with optional filters.
+     * Uses raw API first to preserve user_id in responses, then falls back to SDK-normalized output.
+     */
+    async listConnectedAccounts(options) {
+        const toolkits = normalizeToolkitList(options?.toolkits)?.filter((t) => this.isToolkitAllowed(t));
+        const userIds = options?.userIds
+            ?.map(u => String(u || "").trim())
+            .filter(Boolean);
+        const statuses = this.normalizeStatuses(options?.statuses);
+        if (options?.toolkits && (!toolkits || toolkits.length === 0))
+            return [];
+        try {
+            return await this.listConnectedAccountsRaw({
+                toolkits,
+                userIds,
+                statuses,
+            });
+        }
+        catch {
+            return this.listConnectedAccountsFallback({
+                toolkits,
+                userIds,
+                statuses,
+            });
+        }
+    }
+    /**
+     * Find user IDs that have an active connected account for a toolkit.
+     */
+    async findActiveUserIdsForToolkit(toolkit) {
+        const normalizedToolkit = normalizeToolkitSlug(toolkit);
+        if (!this.isToolkitAllowed(normalizedToolkit))
+            return [];
+        const accounts = await this.listConnectedAccounts({
+            toolkits: [normalizedToolkit],
+            statuses: ["ACTIVE"],
+        });
+        const userIds = new Set();
+        for (const account of accounts) {
+            if (account.userId)
+                userIds.add(account.userId);
+        }
+        return Array.from(userIds).sort();
+    }
+    async listConnectedAccountsRaw(options) {
+        const accounts = [];
+        let cursor;
+        const seenCursors = new Set();
+        do {
+            const response = await this.client.client.connectedAccounts.list({
+                ...(options?.toolkits && options.toolkits.length > 0 ? { toolkit_slugs: options.toolkits } : {}),
+                ...(options?.userIds && options.userIds.length > 0 ? { user_ids: options.userIds } : {}),
+                ...(options?.statuses && options.statuses.length > 0 ? { statuses: options.statuses } : {}),
+                limit: 100,
+                ...(cursor ? { cursor } : {}),
+            });
+            const items = (Array.isArray(response)
+                ? response
+                : response?.items || []);
+            for (const item of items) {
+                const toolkitSlug = normalizeToolkitSlug((item.toolkit?.slug || "").toString());
+                if (!toolkitSlug)
+                    continue;
+                if (!this.isToolkitAllowed(toolkitSlug))
+                    continue;
+                accounts.push({
+                    id: String(item.id || ""),
+                    toolkit: toolkitSlug,
+                    userId: typeof item.user_id === "string" ? item.user_id : undefined,
+                    status: typeof item.status === "string" ? item.status : undefined,
+                    authConfigId: typeof item.auth_config?.id === "string"
+                        ? item.auth_config.id
+                        : undefined,
+                    isDisabled: typeof item.is_disabled === "boolean" ? item.is_disabled : undefined,
+                    createdAt: typeof item.created_at === "string" ? item.created_at : undefined,
+                    updatedAt: typeof item.updated_at === "string" ? item.updated_at : undefined,
+                });
+            }
+            cursor = Array.isArray(response)
+                ? null
+                : (response?.next_cursor ?? null);
+            if (!cursor)
+                break;
+            if (seenCursors.has(cursor))
+                break;
+            seenCursors.add(cursor);
+        } while (true);
+        return accounts;
+    }
+    async listConnectedAccountsFallback(options) {
+        const accounts = [];
+        let cursor;
+        const seenCursors = new Set();
+        do {
+            const response = await this.client.connectedAccounts.list({
+                ...(options?.toolkits && options.toolkits.length > 0 ? { toolkitSlugs: options.toolkits } : {}),
+                ...(options?.userIds && options.userIds.length > 0 ? { userIds: options.userIds } : {}),
+                ...(options?.statuses && options.statuses.length > 0 ? { statuses: options.statuses } : {}),
+                limit: 100,
+                ...(cursor ? { cursor } : {}),
+            });
+            const items = (Array.isArray(response)
+                ? response
+                : response?.items || []);
+            for (const item of items) {
+                const toolkitSlug = normalizeToolkitSlug((item.toolkit?.slug || "").toString());
+                if (!toolkitSlug)
+                    continue;
+                if (!this.isToolkitAllowed(toolkitSlug))
+                    continue;
+                accounts.push({
+                    id: String(item.id || ""),
+                    toolkit: toolkitSlug,
+                    status: typeof item.status === "string" ? item.status : undefined,
+                    authConfigId: typeof item.authConfig?.id === "string"
+                        ? item.authConfig.id
+                        : undefined,
+                    isDisabled: typeof item.isDisabled === "boolean" ? item.isDisabled : undefined,
+                    createdAt: typeof item.createdAt === "string" ? item.createdAt : undefined,
+                    updatedAt: typeof item.updatedAt === "string" ? item.updatedAt : undefined,
+                });
+            }
+            cursor = Array.isArray(response)
+                ? null
+                : (response?.nextCursor ?? null);
+            if (!cursor)
+                break;
+            if (seenCursors.has(cursor))
+                break;
+            seenCursors.add(cursor);
+        } while (true);
+        return accounts;
+    }
     /**
      * Create an auth connection for a toolkit using session.authorize()
      */
     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) {
@@ -219,11 +804,29 @@ export class ComposioClient {
         const uid = this.getUserId(userId);
         try {
             const session = await this.getSession(uid);
-            const response = await session.toolkits();
-            const allToolkits = response.items || [];
-            return allToolkits
-                .map(tk => tk.slug)
-                .filter(slug => this.isToolkitAllowed(slug));
+            const seen = new Set();
+            let nextCursor;
+            const seenCursors = new Set();
+            do {
+                const response = await session.toolkits({
+                    nextCursor,
+                    limit: 100,
+                });
+                const allToolkits = response.items || [];
+                for (const tk of allToolkits) {
+                    const slug = normalizeToolkitSlug(tk.slug);
+                    if (!this.isToolkitAllowed(slug))
+                        continue;
+                    seen.add(slug);
+                }
+                nextCursor = response.nextCursor;
+                if (!nextCursor)
+                    break;
+                if (seenCursors.has(nextCursor))
+                    break;
+                seenCursors.add(nextCursor);
+            } while (true);
+            return Array.from(seen);
         }
         catch (err) {
             const errObj = err;
@@ -239,18 +842,36 @@ 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 response = await this.client.connectedAccounts.list({ userId: uid });
-            const connections = (Array.isArray(response)
-                ? response
-                : response?.items || []);
-            const conn = connections.find(c => c.toolkit?.slug?.toLowerCase() === toolkit.toLowerCase());
-            if (!conn) {
-                return { success: false, error: `No connection found for toolkit '${toolkit}'` };
+            const activeAccounts = await this.listConnectedAccounts({
+                toolkits: [toolkitSlug],
+                userIds: [uid],
+                statuses: ["ACTIVE"],
+            });
+            if (activeAccounts.length === 0) {
+                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 '${toolkitSlug}' accounts found for user_id '${uid}': ${ids}. ` +
+                        "Use the dashboard to disconnect a specific account.",
+                };
             }
-            await this.client.connectedAccounts.delete({ connectedAccountId: conn.id });
+            await this.client.connectedAccounts.delete(activeAccounts[0].id);
             // Clear session cache to refresh connection status
-            this.sessionCache.delete(uid);
+            this.clearUserSessionCache(uid);
             return { success: true };
         }
         catch (err) {