@composio/client 0.1.0-alpha.47 → 0.1.0-alpha.49

package/src/resources/tool-router/session.ts

@@ -2,7 +2,6 @@
 
 import { APIResource } from '../../core/resource';
 import { APIPromise } from '../../core/api-promise';
-import { buildHeaders } from '../../internal/headers';
 import { RequestOptions } from '../../internal/request-options';
 import { path } from '../../internal/utils/path';
 
@@ -56,17 +55,32 @@ export class Session extends APIResource {
    */
   execute(
     sessionID: string,
-    params: SessionExecuteParams,
+    body: SessionExecuteParams,
     options?: RequestOptions,
   ): APIPromise<SessionExecuteResponse> {
-    const { 'x-session-access-key': xSessionAccessKey, ...body } = params;
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute`, {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute`, { body, ...options });
+  }
+
+  /**
+   * Executes a Composio meta tool (COMPOSIO\_\*) within a tool router session.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.toolRouter.session.executeMeta(
+   *     'trs_LX9uJKBinWWr',
+   *     { slug: 'COMPOSIO_MANAGE_CONNECTIONS' },
+   *   );
+   * ```
+   */
+  executeMeta(
+    sessionID: string,
+    body: SessionExecuteMetaParams,
+    options?: RequestOptions,
+  ): APIPromise<SessionExecuteMetaResponse> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute_meta`, {
       body,
       ...options,
-      headers: buildHeaders([
-        { ...(xSessionAccessKey != null ? { 'x-session-access-key': xSessionAccessKey } : undefined) },
-        options?.headers,
-      ]),
     });
   }
 
@@ -159,14 +173,16 @@ export namespace SessionCreateResponse {
     connected_accounts?: { [key: string]: string };
 
     /**
-     * Connections configuration
+     * Manage connections configuration
      */
-    connections?: Config.Connections;
+    manage_connections?: Config.ManageConnections;
 
     /**
-     * Execution configuration
+     * MCP tool annotation hints for filtering tools. readOnlyHint: tool does not
+     * modify environment. destructiveHint: tool may perform destructive updates.
+     * idempotentHint: tool may interact with external entities.
      */
-    execution?: Config.Execution;
+    tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint'>;
 
     /**
      * Toolkit configuration - either enabled list or disabled list
@@ -174,45 +190,38 @@ export namespace SessionCreateResponse {
     toolkits?: Config.Enabled | Config.Disabled;
 
     /**
-     * Tools configuration
+     * Tool-level configuration per toolkit
      */
-    tools?: Config.Tools;
+    tools?: { [key: string]: Config.Enabled | Config.Disabled | Config.Tags };
+
+    /**
+     * Workbench configuration
+     */
+    workbench?: Config.Workbench;
   }
 
   export namespace Config {
     /**
-     * Connections configuration
+     * Manage connections configuration
      */
-    export interface Connections {
-      /**
-       * Whether to enable the connection manager for automatic connection handling
-       */
-      auto_manage_connections?: boolean;
-
+    export interface ManageConnections {
       /**
        * Custom callback URL for connected account auth flows
        */
       callback_url?: string;
 
       /**
-       * Whether to auto-infer auth scopes from tools
+       * Whether to enable the connection manager for automatic connection handling
        */
-      infer_scopes_from_tools?: boolean;
+      enabled?: boolean;
     }
 
-    /**
-     * Execution configuration
-     */
-    export interface Execution {
-      /**
-       * Whether to allow proxy execute calls in the workbench
-       */
-      proxy_execution_enabled?: boolean;
+    export interface Enabled {
+      enabled: Array<string>;
+    }
 
-      /**
-       * Maximum execution time for workbench operations in seconds
-       */
-      timeout_seconds?: number;
+    export interface Disabled {
+      disabled: Array<string>;
     }
 
     export interface Enabled {
@@ -223,56 +232,24 @@ export namespace SessionCreateResponse {
       disabled: Array<string>;
     }
 
+    export interface Tags {
+      tags: Array<string>;
+    }
+
     /**
-     * Tools configuration
+     * Workbench configuration
      */
-    export interface Tools {
+    export interface Workbench {
       /**
-       * Tool filtering configuration
+       * Character threshold after which tool execution response are saved to a file in
+       * workbench. Default is 20k.
        */
-      filters?: Tools.Filters;
+      auto_offload_threshold?: number;
 
       /**
-       * Tool-level overrides per toolkit
+       * Whether proxy execution is enabled in the workbench
        */
-      overrides?: { [key: string]: Tools.Enabled | Tools.Disabled };
-    }
-
-    export namespace Tools {
-      /**
-       * Tool filtering configuration
-       */
-      export interface Filters {
-        /**
-         * Filter tools by specific tags
-         */
-        tags?: Filters.Tags;
-      }
-
-      export namespace Filters {
-        /**
-         * Filter tools by specific tags
-         */
-        export interface Tags {
-          /**
-           * Exclude tools that have these tags
-           */
-          exclude?: Array<string>;
-
-          /**
-           * Only include tools that have these tags
-           */
-          include?: Array<string>;
-        }
-      }
-
-      export interface Enabled {
-        enabled: Array<string>;
-      }
-
-      export interface Disabled {
-        disabled: Array<string>;
-      }
+      proxy_execution_enabled?: boolean;
     }
   }
 
@@ -336,14 +313,16 @@ export namespace SessionRetrieveResponse {
     connected_accounts?: { [key: string]: string };
 
     /**
-     * Connections configuration
+     * Manage connections configuration
      */
-    connections?: Config.Connections;
+    manage_connections?: Config.ManageConnections;
 
     /**
-     * Execution configuration
+     * MCP tool annotation hints for filtering tools. readOnlyHint: tool does not
+     * modify environment. destructiveHint: tool may perform destructive updates.
+     * idempotentHint: tool may interact with external entities.
      */
-    execution?: Config.Execution;
+    tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint'>;
 
     /**
      * Toolkit configuration - either enabled list or disabled list
@@ -351,45 +330,38 @@ export namespace SessionRetrieveResponse {
     toolkits?: Config.Enabled | Config.Disabled;
 
     /**
-     * Tools configuration
+     * Tool-level configuration per toolkit
      */
-    tools?: Config.Tools;
+    tools?: { [key: string]: Config.Enabled | Config.Disabled | Config.Tags };
+
+    /**
+     * Workbench configuration
+     */
+    workbench?: Config.Workbench;
   }
 
   export namespace Config {
     /**
-     * Connections configuration
+     * Manage connections configuration
      */
-    export interface Connections {
-      /**
-       * Whether to enable the connection manager for automatic connection handling
-       */
-      auto_manage_connections?: boolean;
-
+    export interface ManageConnections {
       /**
        * Custom callback URL for connected account auth flows
        */
       callback_url?: string;
 
       /**
-       * Whether to auto-infer auth scopes from tools
+       * Whether to enable the connection manager for automatic connection handling
        */
-      infer_scopes_from_tools?: boolean;
+      enabled?: boolean;
     }
 
-    /**
-     * Execution configuration
-     */
-    export interface Execution {
-      /**
-       * Whether to allow proxy execute calls in the workbench
-       */
-      proxy_execution_enabled?: boolean;
+    export interface Enabled {
+      enabled: Array<string>;
+    }
 
-      /**
-       * Maximum execution time for workbench operations in seconds
-       */
-      timeout_seconds?: number;
+    export interface Disabled {
+      disabled: Array<string>;
     }
 
     export interface Enabled {
@@ -400,56 +372,24 @@ export namespace SessionRetrieveResponse {
       disabled: Array<string>;
     }
 
+    export interface Tags {
+      tags: Array<string>;
+    }
+
     /**
-     * Tools configuration
+     * Workbench configuration
      */
-    export interface Tools {
+    export interface Workbench {
       /**
-       * Tool filtering configuration
+       * Character threshold after which tool execution response are saved to a file in
+       * workbench. Default is 20k.
        */
-      filters?: Tools.Filters;
-
-      /**
-       * Tool-level overrides per toolkit
-       */
-      overrides?: { [key: string]: Tools.Enabled | Tools.Disabled };
-    }
+      auto_offload_threshold?: number;
 
-    export namespace Tools {
       /**
-       * Tool filtering configuration
+       * Whether proxy execution is enabled in the workbench
        */
-      export interface Filters {
-        /**
-         * Filter tools by specific tags
-         */
-        tags?: Filters.Tags;
-      }
-
-      export namespace Filters {
-        /**
-         * Filter tools by specific tags
-         */
-        export interface Tags {
-          /**
-           * Exclude tools that have these tags
-           */
-          exclude?: Array<string>;
-
-          /**
-           * Only include tools that have these tags
-           */
-          include?: Array<string>;
-        }
-      }
-
-      export interface Enabled {
-        enabled: Array<string>;
-      }
-
-      export interface Disabled {
-        disabled: Array<string>;
-      }
+      proxy_execution_enabled?: boolean;
     }
   }
 
@@ -483,6 +423,23 @@ export interface SessionExecuteResponse {
   log_id: string;
 }
 
+export interface SessionExecuteMetaResponse {
+  /**
+   * The data returned by the tool execution
+   */
+  data: { [key: string]: unknown };
+
+  /**
+   * Error message if the execution failed, null otherwise
+   */
+  error: string | null;
+
+  /**
+   * Unique identifier for the execution log
+   */
+  log_id: string;
+}
+
 export interface SessionLinkResponse {
   /**
    * The unique identifier for the connected account
@@ -643,13 +600,16 @@ export interface SessionCreateParams {
   /**
    * Configuration for connection management settings
    */
-  connections?: SessionCreateParams.Connections;
+  manage_connections?: SessionCreateParams.ManageConnections;
 
   /**
-   * Configuration for workbench behavior including security restrictions and
-   * execution limits
+   * Global MCP tool annotation hints for filtering. readOnlyHint: tool does not
+   * modify environment. destructiveHint: tool may perform destructive updates.
+   * idempotentHint: repeated calls with same args have no additional effect.
+   * Toolkit-level tags override this. Toolkit enabled/disabled lists take precedence
+   * over tag filtering.
    */
-  execution?: SessionCreateParams.Execution;
+  tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint'>;
 
   /**
    * Toolkit configuration - specify either enabled toolkits (allowlist) or disabled
@@ -658,24 +618,24 @@ export interface SessionCreateParams {
   toolkits?: SessionCreateParams.Enabled | SessionCreateParams.Disabled;
 
   /**
-   * Configuration for tool overrides and filtering
+   * Tool-level configuration per toolkit - either specify enabled tools (whitelist),
+   * disabled tools (blacklist), or filter by MCP tags for each toolkit
+   */
+  tools?: {
+    [key: string]: SessionCreateParams.Enabled | SessionCreateParams.Disabled | SessionCreateParams.Tags;
+  };
+
+  /**
+   * Configuration for workbench behavior
    */
-  tools?: SessionCreateParams.Tools;
+  workbench?: SessionCreateParams.Workbench;
 }
 
 export namespace SessionCreateParams {
   /**
    * Configuration for connection management settings
    */
-  export interface Connections {
-    /**
-     * Whether to enable the connection manager for automatic connection handling. If
-     * true, we will provide a tool your agent can use to initiate connections to
-     * toolkits if it doesnt exist. If set to false, then you have to manage
-     * connections manually.
-     */
-    auto_manage_connections?: boolean | null;
-
+  export interface ManageConnections {
     /**
      * The URL to redirect to after a user completes authentication for a connected
      * account. This allows you to handle the auth callback in your own application.
@@ -683,29 +643,12 @@ export namespace SessionCreateParams {
     callback_url?: string;
 
     /**
-     * If enabled, authentication scopes will be automatically inferred from the
-     * specific tools being used in the session. This ensures minimal permissions are
-     * requested.
-     */
-    infer_scopes_from_tools?: boolean | null;
-  }
-
-  /**
-   * Configuration for workbench behavior including security restrictions and
-   * execution limits
-   */
-  export interface Execution {
-    /**
-     * Whether to allow proxy execute calls in the workbench. If false, prevents
-     * arbitrary HTTP requests and destructive actions.
-     */
-    proxy_execution_enabled?: boolean | null;
-
-    /**
-     * Maximum allowed execution time for workbench operations in seconds. If not
-     * specified, uses the default timeout.
+     * Whether to enable the connection manager for automatic connection handling. If
+     * true, we will provide a tool your agent can use to initiate connections to
+     * toolkits if it doesnt exist. If set to false, then you have to manage
+     * connections manually.
      */
-    timeout_seconds?: number;
+    enabled?: boolean | null;
   }
 
   /**
@@ -728,88 +671,69 @@ export namespace SessionCreateParams {
     disabled: Array<string>;
   }
 
-  /**
-   * Configuration for tool overrides and filtering
-   */
-  export interface Tools {
+  export interface Enabled {
     /**
-     * Configuration for filtering available tools based on tags and characteristics
+     * Only these specific tools will be available for this toolkit
      */
-    filters?: Tools.Filters;
+    enabled: Array<string>;
+  }
 
+  export interface Disabled {
     /**
-     * Tool-level overrides per toolkit - either specify enabled tools (whitelist) or
-     * disabled tools (blacklist) for each toolkit
+     * These specific tools will be disabled for this toolkit
      */
-    overrides?: { [key: string]: Tools.Enabled | Tools.Disabled };
+    disabled: Array<string>;
   }
 
-  export namespace Tools {
+  export interface Tags {
     /**
-     * Configuration for filtering available tools based on tags and characteristics
+     * MCP tags to filter tools for this toolkit. Only tools with these tags will be
+     * available.
      */
-    export interface Filters {
-      /**
-       * Filter tools by tags such as read_only_hint, non_destructive_hint,
-       * open_world_hint, idempotent_hint. Use include to only show tools with specific
-       * tags, or exclude to hide tools with specific tags.
-       */
-      tags?: Filters.Tags;
-    }
-
-    export namespace Filters {
-      /**
-       * Filter tools by tags such as read_only_hint, non_destructive_hint,
-       * open_world_hint, idempotent_hint. Use include to only show tools with specific
-       * tags, or exclude to hide tools with specific tags.
-       */
-      export interface Tags {
-        /**
-         * Exclude tools that have any of these tags. Tools with any of these tags will be
-         * filtered out.
-         */
-        exclude?: Array<string>;
-
-        /**
-         * Only include tools that have these tags. Tools must have at least one of these
-         * tags to be included.
-         */
-        include?: Array<string>;
-      }
-    }
+    tags: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint'>;
+  }
 
-    export interface Enabled {
-      /**
-       * Only these specific tools will be available for this toolkit
-       */
-      enabled: Array<string>;
-    }
+  /**
+   * Configuration for workbench behavior
+   */
+  export interface Workbench {
+    /**
+     * Character threshold for automatic offloading. When workbench response exceeds
+     * this threshold, it will be automatically offloaded. Default is picked
+     * automatically based on the response size.
+     */
+    auto_offload_threshold?: number;
 
-    export interface Disabled {
-      /**
-       * These specific tools will be disabled for this toolkit
-       */
-      disabled: Array<string>;
-    }
+    /**
+     * Whether proxy execution is enabled. When enabled, workbench can call URLs and
+     * APIs directly.
+     */
+    proxy_execution_enabled?: boolean;
   }
 }
 
 export interface SessionExecuteParams {
   /**
-   * Body param: The unique slug identifier of the tool to execute
+   * The unique slug identifier of the tool to execute
    */
   tool_slug: string;
 
   /**
-   * Body param: The arguments required by the tool
+   * The arguments required by the tool
    */
   arguments?: { [key: string]: unknown };
+}
 
+export interface SessionExecuteMetaParams {
   /**
-   * Header param: Session access key for sandbox/workbench authentication.
-   * Alternative to x-api-key for internal tool router endpoints.
+   * The unique slug identifier of the meta tool to execute
    */
-  'x-session-access-key'?: string;
+  slug: string;
+
+  /**
+   * The arguments required by the meta tool
+   */
+  arguments?: { [key: string]: unknown };
 }
 
 export interface SessionLinkParams {
@@ -856,10 +780,12 @@ export declare namespace Session {
     type SessionCreateResponse as SessionCreateResponse,
     type SessionRetrieveResponse as SessionRetrieveResponse,
     type SessionExecuteResponse as SessionExecuteResponse,
+    type SessionExecuteMetaResponse as SessionExecuteMetaResponse,
     type SessionLinkResponse as SessionLinkResponse,
     type SessionToolkitsResponse as SessionToolkitsResponse,
     type SessionCreateParams as SessionCreateParams,
     type SessionExecuteParams as SessionExecuteParams,
+    type SessionExecuteMetaParams as SessionExecuteMetaParams,
     type SessionLinkParams as SessionLinkParams,
     type SessionToolkitsParams as SessionToolkitsParams,
   };

package/src/resources/tool-router/tool-router.ts

@@ -6,6 +6,8 @@ import {
   Session,
   SessionCreateParams,
   SessionCreateResponse,
+  SessionExecuteMetaParams,
+  SessionExecuteMetaResponse,
   SessionExecuteParams,
   SessionExecuteResponse,
   SessionLinkParams,
@@ -21,10 +23,10 @@ export class ToolRouter extends APIResource {
   session: SessionAPI.Session = new SessionAPI.Session(this._client);
 
   /**
-   * Creates a new session for the tool router lab feature. This endpoint initializes
-   * a new session with specified toolkits and their authentication configurations.
-   * The session provides an isolated environment for testing and managing tool
-   * routing logic with scoped MCP server access.
+   * Creates a new session for the tool router lab feature (Legacy). This endpoint
+   * initializes a new session with specified toolkits and their authentication
+   * configurations. The session provides an isolated environment for testing and
+   * managing tool routing logic with scoped MCP server access.
    *
    * @example
    * ```ts
@@ -127,10 +129,12 @@ export declare namespace ToolRouter {
     type SessionCreateResponse as SessionCreateResponse,
     type SessionRetrieveResponse as SessionRetrieveResponse,
     type SessionExecuteResponse as SessionExecuteResponse,
+    type SessionExecuteMetaResponse as SessionExecuteMetaResponse,
     type SessionLinkResponse as SessionLinkResponse,
     type SessionToolkitsResponse as SessionToolkitsResponse,
     type SessionCreateParams as SessionCreateParams,
     type SessionExecuteParams as SessionExecuteParams,
+    type SessionExecuteMetaParams as SessionExecuteMetaParams,
     type SessionLinkParams as SessionLinkParams,
     type SessionToolkitsParams as SessionToolkitsParams,
   };

package/src/resources/toolkits.ts

@@ -39,11 +39,8 @@ export class Toolkits extends APIResource {
    * purpose when using the toolkit listing endpoint. Categories help organize
    * toolkits into logical groups based on their functionality or industry focus.
    */
-  retrieveCategories(
-    query: ToolkitRetrieveCategoriesParams | null | undefined = {},
-    options?: RequestOptions,
-  ): APIPromise<ToolkitRetrieveCategoriesResponse> {
-    return this._client.get('/api/v3/toolkits/categories', { query, ...options });
+  retrieveCategories(options?: RequestOptions): APIPromise<ToolkitRetrieveCategoriesResponse> {
+    return this._client.get('/api/v3/toolkits/categories', options);
   }
 }
 
@@ -358,7 +355,7 @@ export namespace ToolkitListResponse {
    */
   export interface Item {
     /**
-     * Deprecated toolkit ID
+     * @deprecated Deprecated toolkit ID
      */
     deprecated: Item.Deprecated;
 
@@ -401,7 +398,7 @@ export namespace ToolkitListResponse {
 
   export namespace Item {
     /**
-     * Deprecated toolkit ID
+     * @deprecated Deprecated toolkit ID
      */
     export interface Deprecated {
       toolkitId: string;
@@ -544,13 +541,6 @@ export interface ToolkitListParams {
   sort_by?: 'usage' | 'alphabetically';
 }
 
-export interface ToolkitRetrieveCategoriesParams {
-  /**
-   * Cache control parameter
-   */
-  cache?: string;
-}
-
 export declare namespace Toolkits {
   export {
     type ToolkitRetrieveResponse as ToolkitRetrieveResponse,
@@ -558,6 +548,5 @@ export declare namespace Toolkits {
     type ToolkitRetrieveCategoriesResponse as ToolkitRetrieveCategoriesResponse,
     type ToolkitRetrieveParams as ToolkitRetrieveParams,
     type ToolkitListParams as ToolkitListParams,
-    type ToolkitRetrieveCategoriesParams as ToolkitRetrieveCategoriesParams,
   };
 }