@customclaw/composio 0.0.5 → 0.0.7

package/dist/client.test.js

@@ -2,6 +2,7 @@ import { describe, it, expect, vi } from "vitest";
 import { ComposioClient } from "./client.js";
 import { parseComposioConfig } from "./config.js";
 import { createComposioExecuteTool } from "./tools/execute.js";
+import { createComposioConnectionsTool } from "./tools/connections.js";
 // Mock the Composio SDK
 vi.mock("@composio/core", () => ({
     Composio: vi.fn().mockImplementation(() => ({
@@ -15,6 +16,7 @@ vi.mock("@composio/core", () => ({
                         { slug: "gmail", name: "Gmail", connection: { isActive: true } },
                         { slug: "sentry", name: "Sentry", connection: { isActive: false } },
                         { slug: "github", name: "GitHub", connection: { isActive: true } },
+                        { slug: "affinity", name: "Affinity", connection: { isActive: false } },
                     ],
                 }),
                 experimental: { assistivePrompt: "" },
@@ -27,9 +29,19 @@ vi.mock("@composio/core", () => ({
                     data: { results: [{ tool_slug: "GMAIL_FETCH_EMAILS", index: 0, response: { successful: true, data: { messages: [] } } }] },
                 }),
             },
+            connectedAccounts: {
+                list: vi.fn().mockResolvedValue({ items: [], next_cursor: null }),
+            },
+        },
+        tools: {
+            execute: vi.fn().mockResolvedValue({
+                successful: true,
+                data: { direct: true },
+            }),
         },
         connectedAccounts: {
             list: vi.fn().mockResolvedValue({ items: [] }),
+            get: vi.fn().mockResolvedValue({ toolkit: { slug: "gmail" }, status: "ACTIVE" }),
             delete: vi.fn().mockResolvedValue({}),
         },
     })),
@@ -41,6 +53,11 @@ function makeClient(overrides) {
         ...overrides,
     });
 }
+async function getLatestComposioInstance() {
+    const { Composio } = await import("@composio/core");
+    const mockResults = Composio.mock.results;
+    return mockResults[mockResults.length - 1].value;
+}
 describe("config parsing", () => {
     it("reads apiKey from config object", () => {
         const config = parseComposioConfig({ config: { apiKey: "from-config" } });
@@ -60,6 +77,19 @@ describe("config parsing", () => {
         const config = parseComposioConfig({});
         expect(config.enabled).toBe(true);
     });
+    it("reads defaultUserId and toolkit filters from nested config object", () => {
+        const config = parseComposioConfig({
+            config: {
+                apiKey: "from-config",
+                defaultUserId: "app-user-123",
+                allowedToolkits: ["gmail", "sentry"],
+                blockedToolkits: ["github"],
+            },
+        });
+        expect(config.defaultUserId).toBe("app-user-123");
+        expect(config.allowedToolkits).toEqual(["gmail", "sentry"]);
+        expect(config.blockedToolkits).toEqual(["github"]);
+    });
 });
 describe("toolkit filtering", () => {
     it("allows all toolkits when no filter set", async () => {
@@ -97,6 +127,16 @@ describe("connection status", () => {
         const statuses = await client.getConnectionStatus(["sentry"]);
         expect(statuses[0].connected).toBe(false);
     });
+    it("reports toolkit as connected when active connected account exists", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.connectedAccounts.list.mockResolvedValueOnce({
+            items: [{ toolkit: { slug: "affinity" }, status: "ACTIVE" }],
+            nextCursor: null,
+        });
+        const statuses = await client.getConnectionStatus(["affinity"]);
+        expect(statuses[0].connected).toBe(true);
+    });
     it("returns only connected toolkits when no filter", async () => {
         const client = makeClient();
         const statuses = await client.getConnectionStatus();
@@ -117,6 +157,123 @@ describe("execute tool", () => {
         expect(result.success).toBe(false);
         expect(result.error).toContain("not allowed");
     });
+    it("pins execution to explicit connected_account_id", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.connectedAccounts.get.mockResolvedValueOnce({
+            toolkit: { slug: "gmail" },
+            status: "ACTIVE",
+        });
+        const result = await client.executeTool("GMAIL_FETCH_EMAILS", {}, "default", "ca_explicit");
+        expect(result.success).toBe(true);
+        expect(instance.toolRouter.create).toHaveBeenCalledWith("default", {
+            connectedAccounts: { gmail: "ca_explicit" },
+        });
+    });
+    it("auto-pins execution when one active account exists", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_single", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+            ],
+            next_cursor: null,
+        });
+        const result = await client.executeTool("GMAIL_FETCH_EMAILS", {}, "default");
+        expect(result.success).toBe(true);
+        expect(instance.toolRouter.create).toHaveBeenCalledWith("default", {
+            connectedAccounts: { gmail: "ca_single" },
+        });
+    });
+    it("fails with clear error when multiple active accounts exist and none selected", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_1", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+                { id: "ca_2", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+            ],
+            next_cursor: null,
+        });
+        const result = await client.executeTool("GMAIL_FETCH_EMAILS", {}, "default");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Multiple ACTIVE 'gmail' accounts");
+        expect(result.error).toContain("ca_1");
+        expect(result.error).toContain("ca_2");
+    });
+    it("falls back to direct execute when meta-tool resolves entity as default for non-default user", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_sentry", user_id: "pg-user", status: "ACTIVE", toolkit: { slug: "sentry" } },
+            ],
+            next_cursor: null,
+        });
+        instance.client.tools.execute.mockResolvedValueOnce({
+            successful: false,
+            error: "1 out of 1 tools failed",
+            data: {
+                results: [{ error: "Error: No connected account found for entity ID default for toolkit sentry" }],
+            },
+        });
+        instance.tools.execute.mockResolvedValueOnce({
+            successful: true,
+            data: { ok: true },
+        });
+        const result = await client.executeTool("SENTRY_GET_ORGANIZATION_DETAILS", {}, "pg-user");
+        expect(result.success).toBe(true);
+        expect(result.data).toEqual({ ok: true });
+        expect(instance.tools.execute).toHaveBeenCalledWith("SENTRY_GET_ORGANIZATION_DETAILS", {
+            userId: "pg-user",
+            connectedAccountId: "ca_sentry",
+            arguments: {},
+            dangerouslySkipVersionCheck: true,
+        });
+    });
+    it("retries once with server-hinted identifier value", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_posthog", user_id: "pg-user", status: "ACTIVE", toolkit: { slug: "posthog" } },
+            ],
+            next_cursor: null,
+        });
+        instance.client.tools.execute.mockResolvedValueOnce({
+            successful: true,
+            data: {
+                results: [
+                    {
+                        tool_slug: "POSTHOG_RETRIEVE_USER_PROFILE_AND_TEAM_DETAILS",
+                        index: 0,
+                        response: {
+                            successful: false,
+                            error: JSON.stringify({
+                                type: "authentication_error",
+                                code: "permission_denied",
+                                detail: "As a non-staff user you're only allowed to access the `@me` user instance.",
+                                attr: null,
+                            }),
+                        },
+                    },
+                ],
+            },
+        });
+        instance.tools.execute.mockResolvedValueOnce({
+            successful: true,
+            data: { ok: true, retried: true },
+        });
+        const result = await client.executeTool("POSTHOG_RETRIEVE_USER_PROFILE_AND_TEAM_DETAILS", { uuid: "some-other-uuid" }, "pg-user");
+        expect(result.success).toBe(true);
+        expect(result.data).toEqual({ ok: true, retried: true });
+        expect(instance.tools.execute).toHaveBeenCalledWith("POSTHOG_RETRIEVE_USER_PROFILE_AND_TEAM_DETAILS", {
+            userId: "pg-user",
+            connectedAccountId: "ca_posthog",
+            arguments: { uuid: "@me" },
+            dangerouslySkipVersionCheck: true,
+        });
+    });
 });
 describe("create connection", () => {
     it("returns auth URL", async () => {
@@ -133,6 +290,111 @@ describe("create connection", () => {
         expect("error" in result).toBe(true);
     });
 });
+describe("disconnect toolkit", () => {
+    it("disconnects single active account", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_gmail", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+            ],
+            next_cursor: null,
+        });
+        const result = await client.disconnectToolkit("gmail", "default");
+        expect(result.success).toBe(true);
+        expect(instance.connectedAccounts.delete).toHaveBeenCalledWith({ connectedAccountId: "ca_gmail" });
+    });
+    it("fails safely when multiple active accounts exist", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_1", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+                { id: "ca_2", user_id: "default", status: "ACTIVE", toolkit: { slug: "gmail" } },
+            ],
+            next_cursor: null,
+        });
+        const result = await client.disconnectToolkit("gmail", "default");
+        expect(result.success).toBe(false);
+        expect(result.error).toContain("Multiple ACTIVE 'gmail' accounts");
+        expect(instance.connectedAccounts.delete).not.toHaveBeenCalled();
+    });
+});
+describe("connected accounts discovery", () => {
+    it("lists connected accounts with user IDs from raw API", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                {
+                    id: "ca_1",
+                    user_id: "user-a",
+                    status: "ACTIVE",
+                    toolkit: { slug: "sentry" },
+                    auth_config: { id: "ac_1" },
+                },
+            ],
+            next_cursor: null,
+        });
+        const accounts = await client.listConnectedAccounts({ toolkits: ["sentry"], statuses: ["ACTIVE"] });
+        expect(instance.client.connectedAccounts.list).toHaveBeenCalledWith({
+            toolkit_slugs: ["sentry"],
+            statuses: ["ACTIVE"],
+            limit: 100,
+        });
+        expect(accounts).toEqual([
+            {
+                id: "ca_1",
+                toolkit: "sentry",
+                userId: "user-a",
+                status: "ACTIVE",
+                authConfigId: "ac_1",
+                isDisabled: undefined,
+                createdAt: undefined,
+                updatedAt: undefined,
+            },
+        ]);
+    });
+    it("falls back to SDK-normalized account list when raw API errors", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockRejectedValueOnce(new Error("raw unavailable"));
+        instance.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                {
+                    id: "ca_2",
+                    status: "ACTIVE",
+                    toolkit: { slug: "gmail" },
+                    authConfig: { id: "ac_2" },
+                    isDisabled: false,
+                },
+            ],
+            nextCursor: null,
+        });
+        const accounts = await client.listConnectedAccounts({ toolkits: ["gmail"], statuses: ["ACTIVE"] });
+        expect(accounts[0]).toMatchObject({
+            id: "ca_2",
+            toolkit: "gmail",
+            status: "ACTIVE",
+            authConfigId: "ac_2",
+            isDisabled: false,
+        });
+    });
+    it("finds active user IDs for toolkit", async () => {
+        const client = makeClient();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                { id: "ca_1", user_id: "default", status: "ACTIVE", toolkit: { slug: "sentry" } },
+                { id: "ca_2", user_id: "user-b", status: "ACTIVE", toolkit: { slug: "sentry" } },
+                { id: "ca_3", user_id: "default", status: "ACTIVE", toolkit: { slug: "sentry" } },
+            ],
+            next_cursor: null,
+        });
+        const userIds = await client.findActiveUserIdsForToolkit("sentry");
+        expect(userIds).toEqual(["default", "user-b"]);
+    });
+});
 describe("session caching", () => {
     it("reuses session for same user", async () => {
         const client = makeClient();
@@ -182,3 +444,63 @@ describe("execute tool string arguments (GLM-5 workaround)", () => {
         expect(result.details).toHaveProperty("success", true);
     });
 });
+describe("connections tool", () => {
+    function makeConnectionsTool() {
+        const client = makeClient();
+        const config = parseComposioConfig({ config: { apiKey: "test-key" } });
+        return createComposioConnectionsTool(client, config);
+    }
+    it("list action passes user_id to client", async () => {
+        const tool = makeConnectionsTool();
+        await tool.execute("test", { action: "list", user_id: "custom-user" });
+        const instance = await getLatestComposioInstance();
+        expect(instance.toolRouter.create).toHaveBeenCalledWith("custom-user", undefined);
+    });
+    it("status uses active connected accounts as fallback", async () => {
+        const tool = makeConnectionsTool();
+        const instance = await getLatestComposioInstance();
+        instance.connectedAccounts.list.mockResolvedValueOnce({
+            items: [{ toolkit: { slug: "affinity" }, status: "ACTIVE" }],
+            nextCursor: null,
+        });
+        const result = await tool.execute("test", { action: "status", toolkit: "affinity" });
+        const details = result.details;
+        const conn = details.connections.find((c) => c.toolkit === "affinity");
+        expect(conn.connected).toBe(true);
+        expect(instance.client.tools.execute).not.toHaveBeenCalledWith("AFFINITY_GET_METADATA_ON_ALL_LISTS", expect.anything());
+    });
+    it("status keeps disconnected when no active account exists", async () => {
+        const tool = makeConnectionsTool();
+        const result = await tool.execute("test", { action: "status", toolkit: "sentry" });
+        const details = result.details;
+        const conn = details.connections.find((c) => c.toolkit === "sentry");
+        expect(conn.connected).toBe(false);
+    });
+    it("accounts action returns connected accounts", async () => {
+        const tool = makeConnectionsTool();
+        const instance = await getLatestComposioInstance();
+        instance.client.connectedAccounts.list.mockResolvedValueOnce({
+            items: [
+                {
+                    id: "ca_1",
+                    user_id: "user-a",
+                    status: "ACTIVE",
+                    toolkit: { slug: "sentry" },
+                    auth_config: { id: "ac_1" },
+                },
+            ],
+            next_cursor: null,
+        });
+        const result = await tool.execute("test", { action: "accounts", toolkit: "sentry" });
+        const details = result.details;
+        expect(details.action).toBe("accounts");
+        expect(details.count).toBe(1);
+        expect(details.accounts[0]).toMatchObject({
+            id: "ca_1",
+            toolkit: "sentry",
+            user_id: "user-a",
+            status: "ACTIVE",
+            auth_config_id: "ac_1",
+        });
+    });
+});

package/dist/config.js

@@ -16,15 +16,28 @@ export function parseComposioConfig(value) {
     const raw = value && typeof value === "object" && !Array.isArray(value)
         ? value
         : {};
-    // Allow API key from config.apiKey, top-level apiKey, or environment
+    // 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()) ||
         process.env.COMPOSIO_API_KEY ||
         "";
     return ComposioConfigSchema.parse({
-        ...raw,
+        enabled,
         apiKey,
+        defaultUserId,
+        allowedToolkits,
+        blockedToolkits,
     });
 }
 /**

package/dist/index.js

@@ -73,22 +73,6 @@ const composioPlugin = {
             config,
             logger: api.logger,
         }), { commands: ["composio"] });
-        // Inject agent instructions via before_agent_start hook
-        api.on("before_agent_start", () => {
-            return {
-                prependContext: `<composio-tools>
-You have access to Composio tools for third-party integrations (Gmail, Sentry, etc.).
-
-## Usage
-1. Use \`composio_search_tools\` to find tools and their parameter schemas.
-2. Use \`composio_manage_connections\` with action="status" to check if a toolkit is connected. Use action="create" to generate an auth URL if needed.
-3. Use \`composio_execute_tool\` with the tool_slug and arguments from search results.
-
-Always search first to get the correct parameter schema before executing a tool.
-Tool slugs are uppercase. If a tool fails with auth errors, prompt the user to connect the toolkit.
-</composio-tools>`,
-            };
-        });
         api.logger.info("[composio] Plugin registered with 3 tools and CLI commands");
     },
 };

package/dist/tools/connections.d.ts

@@ -4,10 +4,11 @@ import type { ComposioConfig } from "../types.js";
  * Tool parameters for composio_manage_connections
  */
 export declare const ComposioManageConnectionsToolSchema: import("@sinclair/typebox").TObject<{
-    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">]>;
+    action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"accounts">]>;
     toolkit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    statuses: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
 }>;
 /**
  * Create the composio_manage_connections tool
@@ -17,10 +18,11 @@ export declare function createComposioConnectionsTool(client: ComposioClient, _c
     label: string;
     description: string;
     parameters: import("@sinclair/typebox").TObject<{
-        action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">]>;
+        action: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"status">, import("@sinclair/typebox").TLiteral<"create">, import("@sinclair/typebox").TLiteral<"list">, import("@sinclair/typebox").TLiteral<"accounts">]>;
         toolkit: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         toolkits: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
         user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        statuses: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TArray<import("@sinclair/typebox").TString>>;
     }>;
     execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
         content: {
@@ -32,6 +34,22 @@ export declare function createComposioConnectionsTool(client: ComposioClient, _c
             count: number;
             toolkits: string[];
         };
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        details: {
+            action: string;
+            count: number;
+            accounts: {
+                id: string;
+                toolkit: string;
+                user_id: string | undefined;
+                status: string | undefined;
+                auth_config_id: string | undefined;
+            }[];
+        };
     } | {
         content: {
             type: string;

package/dist/tools/connections.js

@@ -3,8 +3,8 @@ import { Type } from "@sinclair/typebox";
  * Tool parameters for composio_manage_connections
  */
 export const ComposioManageConnectionsToolSchema = Type.Object({
-    action: Type.Union([Type.Literal("status"), Type.Literal("create"), Type.Literal("list")], {
-        description: "Action to perform: 'status' to check connections, 'create' to initiate auth, 'list' to list toolkits",
+    action: Type.Union([Type.Literal("status"), Type.Literal("create"), Type.Literal("list"), Type.Literal("accounts")], {
+        description: "Action to perform: 'status' to check connections, 'create' to initiate auth, 'list' to list toolkits, 'accounts' to inspect connected accounts",
     }),
     toolkit: Type.Optional(Type.String({
         description: "Toolkit name for 'status' or 'create' actions (e.g., 'github', 'gmail')",
@@ -15,6 +15,9 @@ export const ComposioManageConnectionsToolSchema = Type.Object({
     user_id: Type.Optional(Type.String({
         description: "User ID for session scoping (uses default if not provided)",
     })),
+    statuses: Type.Optional(Type.Array(Type.String(), {
+        description: "Optional connection statuses filter for 'accounts' (e.g., ['ACTIVE'])",
+    })),
 });
 /**
  * Create the composio_manage_connections tool
@@ -23,8 +26,10 @@ export function createComposioConnectionsTool(client, _config) {
     return {
         name: "composio_manage_connections",
         label: "Composio Manage Connections",
-        description: "Manage Composio toolkit connections. Check connection status, create new auth links, " +
-            "or list available toolkits. Use this before executing tools to ensure authentication.",
+        description: "Manage Composio toolkit connections. Use action='status' to check if a toolkit is connected, " +
+            "action='create' to generate an auth URL when disconnected, action='list' to see available toolkits, " +
+            "or action='accounts' to inspect connected accounts across user IDs. " +
+            "Check connection status before executing tools with composio_execute_tool.",
         parameters: ComposioManageConnectionsToolSchema,
         async execute(_toolCallId, params) {
             const action = String(params.action || "status");
@@ -32,7 +37,7 @@ export function createComposioConnectionsTool(client, _config) {
             try {
                 switch (action) {
                     case "list": {
-                        const toolkits = await client.listToolkits();
+                        const toolkits = await client.listToolkits(userId);
                         const response = {
                             action: "list",
                             count: toolkits.length,
@@ -43,6 +48,38 @@ export function createComposioConnectionsTool(client, _config) {
                             details: response,
                         };
                     }
+                    case "accounts": {
+                        let toolkits;
+                        if (typeof params.toolkit === "string" && params.toolkit.trim()) {
+                            toolkits = [params.toolkit.trim()];
+                        }
+                        else if (Array.isArray(params.toolkits)) {
+                            toolkits = params.toolkits.filter((t) => typeof t === "string" && t.trim() !== "");
+                        }
+                        const statuses = Array.isArray(params.statuses)
+                            ? params.statuses.filter((s) => typeof s === "string" && s.trim() !== "")
+                            : ["ACTIVE"];
+                        const accounts = await client.listConnectedAccounts({
+                            toolkits,
+                            userIds: userId ? [userId] : undefined,
+                            statuses,
+                        });
+                        const response = {
+                            action: "accounts",
+                            count: accounts.length,
+                            accounts: accounts.map((a) => ({
+                                id: a.id,
+                                toolkit: a.toolkit,
+                                user_id: a.userId,
+                                status: a.status,
+                                auth_config_id: a.authConfigId,
+                            })),
+                        };
+                        return {
+                            content: [{ type: "text", text: JSON.stringify(response, null, 2) }],
+                            details: response,
+                        };
+                    }
                     case "create": {
                         const toolkit = String(params.toolkit || "").trim();
                         if (!toolkit) {

package/dist/tools/execute.d.ts

@@ -7,6 +7,7 @@ export declare const ComposioExecuteToolSchema: import("@sinclair/typebox").TObj
     tool_slug: import("@sinclair/typebox").TString;
     arguments: import("@sinclair/typebox").TUnknown;
     user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    connected_account_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
 }>;
 /**
  * Create the composio_execute_tool tool
@@ -19,6 +20,7 @@ export declare function createComposioExecuteTool(client: ComposioClient, _confi
         tool_slug: import("@sinclair/typebox").TString;
         arguments: import("@sinclair/typebox").TUnknown;
         user_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        connected_account_id: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
     }>;
     execute(_toolCallId: string, params: Record<string, unknown>): Promise<{
         content: {

package/dist/tools/execute.js

@@ -12,6 +12,9 @@ export const ComposioExecuteToolSchema = Type.Object({
     user_id: Type.Optional(Type.String({
         description: "User ID for session scoping (uses default if not provided)",
     })),
+    connected_account_id: Type.Optional(Type.String({
+        description: "Optional connected account ID to pin execution to a specific account when multiple are connected",
+    })),
 });
 /**
  * Create the composio_execute_tool tool
@@ -20,8 +23,9 @@ export function createComposioExecuteTool(client, _config) {
     return {
         name: "composio_execute_tool",
         label: "Composio Execute Tool",
-        description: "Execute a single Composio tool. Use composio_search_tools first to find the tool slug " +
-            "and parameter schema. The tool must be connected (use composio_manage_connections to check).",
+        description: "Execute a single Composio tool. Use composio_search_tools first to find the UPPERCASE tool slug " +
+            "and parameter schema. The toolkit must be connected — use composio_manage_connections to check " +
+            "status or create an auth link. If execution fails with auth errors, prompt the user to reconnect.",
         parameters: ComposioExecuteToolSchema,
         async execute(_toolCallId, params) {
             const toolSlug = String(params.tool_slug || "").trim();
@@ -42,8 +46,9 @@ export function createComposioExecuteTool(client, _config) {
                 ? rawArgs
                 : {};
             const userId = typeof params.user_id === "string" ? params.user_id : undefined;
+            const connectedAccountId = typeof params.connected_account_id === "string" ? params.connected_account_id : undefined;
             try {
-                const result = await client.executeTool(toolSlug, args, userId);
+                const result = await client.executeTool(toolSlug, args, userId, connectedAccountId);
                 const response = {
                     tool_slug: toolSlug,
                     success: result.success,

package/dist/tools/search.js

@@ -23,8 +23,9 @@ export function createComposioSearchTool(client, _config) {
     return {
         name: "composio_search_tools",
         label: "Composio Search Tools",
-        description: "Search for tools across 1000+ integrations (Gmail, Slack, GitHub, Notion, etc.) " +
-            "by describing what you want to accomplish. Returns matching tools with their schemas.",
+        description: "Search for Composio tools across 1000+ integrations (Gmail, Slack, GitHub, Notion, etc.) " +
+            "by describing what you want to accomplish. Returns matching tools with their UPPERCASE slugs and parameter schemas. " +
+            "Always search first before executing a tool with composio_execute_tool.",
         parameters: ComposioSearchToolSchema,
         async execute(_toolCallId, params) {
             const query = String(params.query || "").trim();

package/dist/types.d.ts

@@ -26,3 +26,13 @@ export interface ConnectionStatus {
     userId?: string;
     authUrl?: string;
 }
+export interface ConnectedAccountSummary {
+    id: string;
+    toolkit: string;
+    userId?: string;
+    status?: string;
+    authConfigId?: string;
+    isDisabled?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@customclaw/composio",
-  "version": "0.0.5",
+  "version": "0.0.7",
   "type": "module",
   "description": "Composio Tool Router plugin for OpenClaw — access 1000+ third-party integrations",
   "main": "dist/index.js",