@composio/client 0.1.0-alpha.68 → 0.1.0-alpha.69

package/resources/tool-router/session/session.d.mts

@@ -35,16 +35,32 @@ export declare class Session extends APIResource {
      */
     retrieve(sessionID: string, options?: RequestOptions): APIPromise<SessionRetrieveResponse>;
     /**
-     * Executes a specific tool within a tool router session. This is the primary
-     * execution endpoint for both meta tools and app tools exposed by the session. The
-     * toolkit is automatically inferred from the tool slug. For app tools, the tool
-     * must belong to an allowed toolkit and must not be disabled in the session
-     * configuration. The endpoint validates permissions, resolves connected accounts
-     * when needed, and executes the tool with the session context. The top-level
-     * account field applies only to direct app tool execution in multi-account
-     * sessions. Meta/helper tools either ignore it or define their own
-     * account-selection fields, for example
-     * COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.
+     * Fetch an existing tool router session by ID.
+     *
+     * @example
+     * ```ts
+     * const response = await client.toolRouter.session.attach(
+     *   'trs_1a2b3c4d5e6f',
+     * );
+     * ```
+     */
+    attach(sessionID: string, body?: SessionAttachParams | null | undefined, options?: RequestOptions): APIPromise<SessionAttachResponse>;
+    /**
+     * Returns the session config history ordered by version DESC (newest first). The
+     * live (current) config appears once, on the first page only, with
+     * `is_current: true`; archived versions have `is_current: false`.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.toolRouter.session.configHistory(
+     *     'trs_1a2b3c4d5e6f',
+     *   );
+     * ```
+     */
+    configHistory(sessionID: string, query?: SessionConfigHistoryParams | null | undefined, options?: RequestOptions): APIPromise<SessionConfigHistoryResponse>;
+    /**
+     * Execute a tool (meta or app) within an existing tool router session.
      *
      * @example
      * ```ts
@@ -56,9 +72,8 @@ export declare class Session extends APIResource {
      */
     execute(sessionID: string, body: SessionExecuteParams, options?: RequestOptions): APIPromise<SessionExecuteResponse>;
     /**
-     * Executes a Composio meta tool (COMPOSIO\_\*) within a tool router session. This
-     * endpoint is kept for meta-tool compatibility; clients can also use the primary
-     * /execute endpoint.
+     * Execute a Composio meta tool (COMPOSIO\_\*) within an existing tool router
+     * session.
      *
      * @example
      * ```ts
@@ -84,6 +99,20 @@ export declare class Session extends APIResource {
      * ```
      */
     link(sessionID: string, body: SessionLinkParams, options?: RequestOptions): APIPromise<SessionLinkResponse>;
+    /**
+     * Partially updates the configuration of an existing tool router session. Only the
+     * fields provided in the request body will be updated. Uses optimistic concurrency
+     * control to prevent lost updates. The previous config is stored in config
+     * history.
+     *
+     * @example
+     * ```ts
+     * const response = await client.toolRouter.session.patch(
+     *   'trs_1a2b3c4d5e6f',
+     * );
+     * ```
+     */
+    patch(sessionID: string, body?: SessionPatchParams | null | undefined, options?: RequestOptions): APIPromise<SessionPatchResponse>;
     /**
      * Execute any native API call on a toolkit with authentication automatically
      * injected from Composio. This endpoint proxies HTTP requests to third-party APIs
@@ -108,9 +137,8 @@ export declare class Session extends APIResource {
      */
     proxyExecute(sessionID: string, body: SessionProxyExecuteParams, options?: RequestOptions): APIPromise<SessionProxyExecuteResponse>;
     /**
-     * Search for tools matching a given use case query within a tool router session.
-     * Returns matching tool slugs, full tool schemas, toolkit connection statuses, and
-     * workflow guidance in a predictable format.
+     * Search for tools matching a use case query within an existing tool router
+     * session.
      *
      * @example
      * ```ts
@@ -139,9 +167,8 @@ export declare class Session extends APIResource {
      */
     toolkits(sessionID: string, query?: SessionToolkitsParams | null | undefined, options?: RequestOptions): APIPromise<SessionToolkitsResponse>;
     /**
-     * Returns the tools available in a tool router session with their complete
-     * schemas. This includes both meta tools and any preloaded app tools exposed by
-     * the session.
+     * Returns tools available in a tool router session with complete schemas. Results
+     * are paginated; use `next_cursor` to fetch the next page.
      *
      * @example
      * ```ts
@@ -154,7 +181,7 @@ export declare class Session extends APIResource {
 }
 export interface SessionCreateResponse {
     /**
-     * The session configuration including user, toolkits, and overrides
+     * The configuration used to create this session
      */
     config: SessionCreateResponse.Config;
     /**
@@ -184,17 +211,22 @@ export interface SessionCreateResponse {
 }
 export declare namespace SessionCreateResponse {
     /**
-     * The session configuration including user, toolkits, and overrides
+     * The configuration used to create this session
      */
     interface Config {
         /**
-         * Preload configuration. Controls which tools appear in `session.tools` and the
-         * MCP server tool list, callable directly without going through search. Each
-         * preloaded tool adds to the agent context — roughly ≤20 tools is recommended.
-         * Always present in the response (empty `tools: []` when the session was created
-         * without a preload config).
+         * Execute helper configuration
+         */
+        execute: Config.Execute;
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
         preload: Config.Preload;
+        /**
+         * Search helper configuration
+         */
+        search: Config.Search;
         /**
          * User identifier for this session
          */
@@ -243,19 +275,27 @@ export declare namespace SessionCreateResponse {
     }
     namespace Config {
         /**
-         * Preload configuration. Controls which tools appear in `session.tools` and the
-         * MCP server tool list, callable directly without going through search. Each
-         * preloaded tool adds to the agent context — roughly ≤20 tools is recommended.
-         * Always present in the response (empty `tools: []` when the session was created
-         * without a preload config).
+         * Execute helper configuration
+         */
+        interface Execute {
+            enable_multi_execute?: boolean;
+        }
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
         interface Preload {
             /**
-             * Tool slugs preloaded for this session. Appear in `session.tools` and the MCP
-             * server tool list, callable directly without going through search. Empty array
-             * when no preload was configured.
+             * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+             * app tools allowed by its filters.
              */
-            tools: Array<string>;
+            tools: Array<string> | 'all';
+        }
+        /**
+         * Search helper configuration
+         */
+        interface Search {
+            enable?: boolean;
         }
         /**
          * Manage connections configuration
@@ -455,7 +495,7 @@ export declare namespace SessionCreateResponse {
 }
 export interface SessionRetrieveResponse {
     /**
-     * The session configuration including user, toolkits, and overrides
+     * The configuration used to create this session
      */
     config: SessionRetrieveResponse.Config;
     /**
@@ -484,17 +524,22 @@ export interface SessionRetrieveResponse {
 }
 export declare namespace SessionRetrieveResponse {
     /**
-     * The session configuration including user, toolkits, and overrides
+     * The configuration used to create this session
      */
     interface Config {
         /**
-         * Preload configuration. Controls which tools appear in `session.tools` and the
-         * MCP server tool list, callable directly without going through search. Each
-         * preloaded tool adds to the agent context — roughly ≤20 tools is recommended.
-         * Always present in the response (empty `tools: []` when the session was created
-         * without a preload config).
+         * Execute helper configuration
+         */
+        execute: Config.Execute;
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
         preload: Config.Preload;
+        /**
+         * Search helper configuration
+         */
+        search: Config.Search;
         /**
          * User identifier for this session
          */
@@ -543,19 +588,27 @@ export declare namespace SessionRetrieveResponse {
     }
     namespace Config {
         /**
-         * Preload configuration. Controls which tools appear in `session.tools` and the
-         * MCP server tool list, callable directly without going through search. Each
-         * preloaded tool adds to the agent context — roughly ≤20 tools is recommended.
-         * Always present in the response (empty `tools: []` when the session was created
-         * without a preload config).
+         * Execute helper configuration
+         */
+        interface Execute {
+            enable_multi_execute?: boolean;
+        }
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
         interface Preload {
             /**
-             * Tool slugs preloaded for this session. Appear in `session.tools` and the MCP
-             * server tool list, callable directly without going through search. Empty array
-             * when no preload was configured.
+             * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+             * app tools allowed by its filters.
              */
-            tools: Array<string>;
+            tools: Array<string> | 'all';
+        }
+        /**
+         * Search helper configuration
+         */
+        interface Search {
+            enable?: boolean;
         }
         /**
          * Manage connections configuration
@@ -752,222 +805,1073 @@ export declare namespace SessionRetrieveResponse {
         message: string;
     }
 }
-export interface SessionExecuteResponse {
-    /**
-     * 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 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
-     */
-    connected_account_id: string;
+export interface SessionAttachResponse {
     /**
-     * Token used to complete the authentication flow
+     * The configuration used to create this session
      */
-    link_token: string;
+    config: SessionAttachResponse.Config;
     /**
-     * The URL where users should be redirected to complete OAuth
+     * Monotonic version of the config. Incremented on each PATCH. Use for optimistic
+     * concurrency control.
      */
-    redirect_url: string;
-}
-export interface SessionProxyExecuteResponse {
+    config_version: number;
+    mcp: SessionAttachResponse.Mcp;
     /**
-     * The HTTP status code returned from the proxied API
+     * The identifier of the session
      */
-    status: number;
+    session_id: string;
     /**
-     * Binary body response data. Present when the response is a binary file.
+     * List of available tools in this session
      */
-    binary_data?: SessionProxyExecuteResponse.BinaryData;
+    tool_router_tools: Array<string>;
     /**
-     * The response data returned from the proxied API
+     * Experimental features
      */
-    data?: unknown;
+    experimental?: SessionAttachResponse.Experimental;
     /**
-     * The HTTP headers returned from the proxied API
+     * Advisory list — the session exists and is usable, but the listed issues may
+     * warrant attention.
      */
-    headers?: {
-        [key: string]: string;
-    };
+    warnings?: Array<SessionAttachResponse.Warning>;
 }
-export declare namespace SessionProxyExecuteResponse {
+export declare namespace SessionAttachResponse {
     /**
-     * Binary body response data. Present when the response is a binary file.
+     * The configuration used to create this session
      */
-    interface BinaryData {
-        /**
-         * Content-Type of the binary data
-         */
-        content_type: string;
-        /**
-         * File size in bytes
-         */
-        size: number;
-        /**
-         * URL to download binary content
-         */
-        url: string;
+    interface Config {
         /**
-         * ISO 8601 timestamp when the URL expires
+         * Execute helper configuration
          */
-        expires_at?: string;
-    }
-}
-export interface SessionSearchResponse {
-    /**
-     * Error message if any searches failed, null if all succeeded. Format: "X out of Y
-     * searches failed, reasons: <details>"
-     */
-    error: string | null;
-    /**
-     * Combined workflow guidance covering connections, planner, and memory usage. Each
-     * element is a step instruction.
-     */
-    next_steps_guidance: Array<string>;
-    /**
-     * Per-query search results with tools, reasoning, and memory. One entry per query
-     * in request order.
-     */
-    results: Array<SessionSearchResponse.Result>;
-    /**
-     * Session info for correlating meta tool calls
-     */
-    session: SessionSearchResponse.Session;
-    /**
-     * Whether all searches completed successfully. False if any query failed.
-     */
-    success: boolean;
-    /**
-     * Time information for the query
-     */
-    time_info: SessionSearchResponse.TimeInfo;
-    /**
-     * Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool
-     * appears once even if used in multiple queries.
-     */
-    tool_schemas: {
-        [key: string]: SessionSearchResponse.ToolSchemas;
-    };
-    /**
-     * Connection status for all toolkits mentioned across all queries, with
-     * descriptions merged in.
-     */
-    toolkit_connection_statuses: Array<SessionSearchResponse.ToolkitConnectionStatus>;
-}
-export declare namespace SessionSearchResponse {
-    interface Result {
+        execute: Config.Execute;
         /**
-         * 1-based index of the query in the request
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
-        index: number;
+        preload: Config.Preload;
         /**
-         * List of main tool slugs matching the search criteria
+         * Search helper configuration
          */
-        primary_tool_slugs: Array<string>;
+        search: Config.Search;
         /**
-         * List of related tool slugs that might be useful
+         * User identifier for this session
          */
-        related_tool_slugs: Array<string>;
+        user_id: string;
         /**
-         * List of unique toolkit slugs used by tools in this query
+         * Auth config overrides per toolkit
          */
-        toolkits: Array<string>;
+        auth_configs?: {
+            [key: string]: string;
+        };
         /**
-         * The use case that was searched
+         * Connected account overrides per toolkit. Each connected account must belong to
+         * the same user_id as the session.
          */
-        use_case: string;
+        connected_accounts?: {
+            [key: string]: string;
+        };
         /**
-         * Task difficulty assessment (e.g., "easy - Simple single-tool operation with
-         * known parameters")
+         * Manage connections configuration
          */
-        difficulty?: string;
+        manage_connections?: Config.ManageConnections;
         /**
-         * Error message if the search for this query failed, null otherwise. Always
-         * present for failed queries.
+         * Multi-account configuration for this session.
          */
-        error?: string | null;
+        multi_account?: Config.MultiAccount;
         /**
-         * Guidance message about the search results, particularly when a cached plan is
-         * available
+         * MCP tool annotation hints for filtering tools with enabled/disabled support.
+         * enabled: tags that the tool must have at least one of. disabled: tags that the
+         * tool must NOT have any of. Both conditions must be satisfied.
          */
-        execution_guidance?: string;
+        tags?: Config.Tags;
         /**
-         * Common pitfalls and considerations (only present when cached plan is available)
+         * Toolkit configuration - either enabled list or disabled list
          */
-        known_pitfalls?: Array<string>;
+        toolkits?: Config.Enabled | Config.Disabled;
         /**
-         * Memory data relevant to this query, grouped by app. Only present for non-cached
-         * search results.
+         * Tool-level configuration per toolkit
          */
-        memory?: {
-            [key: string]: Array<string>;
+        tools?: {
+            [key: string]: Config.Enabled | Config.Disabled | Config.Tags;
         };
         /**
-         * ID of cached plan if available
+         * Workbench configuration
          */
-        plan_id?: string;
+        workbench?: Config.Workbench;
+    }
+    namespace Config {
         /**
-         * Workflow steps from cached plan (only present when cached plan is available)
+         * Execute helper configuration
          */
-        recommended_plan_steps?: Array<string>;
+        interface Execute {
+            enable_multi_execute?: boolean;
+        }
         /**
-         * Reference Python code snippets for processing tool responses in the workbench
-         * (only present when cached plan is available)
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
          */
-        reference_workbench_snippets?: Array<Result.ReferenceWorkbenchSnippet>;
-    }
-    namespace Result {
-        interface ReferenceWorkbenchSnippet {
-            /**
-             * Python code snippet for the workbench
-             */
-            code: string;
+        interface Preload {
             /**
-             * Description of what the code snippet does
+             * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+             * app tools allowed by its filters.
              */
-            description: string;
+            tools: Array<string> | 'all';
         }
-    }
-    /**
-     * Session info for correlating meta tool calls
-     */
-    interface Session {
         /**
-         * Session identifier to be passed to subsequent meta tool calls as session_id.
+         * Search helper configuration
          */
-        id: string;
+        interface Search {
+            enable?: boolean;
+        }
         /**
-         * Whether a fresh session id was generated in this call.
+         * Manage connections configuration
          */
-        generate_id: boolean;
+        interface ManageConnections {
+            /**
+             * Custom callback URL for connected account auth flows
+             */
+            callback_url?: string;
+            /**
+             * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
+             */
+            enable_connection_removal?: boolean;
+            /**
+             * Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status.
+             * Default false. May not work reliably with GPT models.
+             */
+            enable_wait_for_connections?: boolean;
+            /**
+             * Whether to enable the connection manager for automatic connection handling
+             */
+            enabled?: boolean;
+        }
+        /**
+         * Multi-account configuration for this session.
+         */
+        interface MultiAccount {
+            /**
+             * When true, enables multi-account mode for this session. When not set, falls back
+             * to org/project-level configuration.
+             */
+            enable?: boolean;
+            /**
+             * Maximum number of connected accounts allowed per toolkit. Defaults to 5 when
+             * multi-account is enabled.
+             */
+            max_accounts_per_toolkit?: number;
+            /**
+             * When true, require explicit account selection when multiple accounts are
+             * connected. When false (default), use the first/default account.
+             */
+            require_explicit_selection?: boolean;
+        }
+        /**
+         * MCP tool annotation hints for filtering tools with enabled/disabled support.
+         * enabled: tags that the tool must have at least one of. disabled: tags that the
+         * tool must NOT have any of. Both conditions must be satisfied.
+         */
+        interface Tags {
+            /**
+             * Tags that the tool must NOT have any of
+             */
+            disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            /**
+             * Tags that the tool must have at least one of
+             */
+            enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        interface Tags {
+            tags: Tags.Tags;
+        }
+        namespace Tags {
+            interface Tags {
+                /**
+                 * Tags that the tool must NOT have any of
+                 */
+                disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+                /**
+                 * Tags that the tool must have at least one of
+                 */
+                enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            }
+        }
+        /**
+         * Workbench configuration
+         */
+        interface Workbench {
+            /**
+             * Character threshold after which tool execution response are saved to a file in
+             * workbench. Default is 20k.
+             */
+            auto_offload_threshold?: number;
+            /**
+             * Whether the workbench (code execution sandbox) is enabled. When false,
+             * COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
+             */
+            enable?: boolean;
+            /**
+             * Whether proxy execution is enabled in the workbench
+             */
+            proxy_execution_enabled?: boolean;
+            /**
+             * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
+             * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+             */
+            sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
+        }
+    }
+    interface Mcp {
+        /**
+         * The type of the MCP server. Can be http
+         */
+        type: 'http';
+        /**
+         * The URL of the MCP server
+         */
+        url: string;
+    }
+    /**
+     * Experimental features
+     */
+    interface Experimental {
+        /**
+         * The assistive system prompt for the tool router session
+         */
+        assistive_prompt?: string;
+        /**
+         * User-defined custom toolkits with grouped tools (no-auth)
+         */
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
+        /**
+         * Custom tools — standalone or extending Composio toolkits
+         */
+        custom_tools?: Array<Experimental.CustomTool>;
+    }
+    namespace Experimental {
+        interface CustomToolkit {
+            description: string;
+            name: string;
+            slug: string;
+            tools: Array<CustomToolkit.Tool>;
+        }
+        namespace CustomToolkit {
+            interface Tool {
+                description: string;
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                name: string;
+                /**
+                 * Original tool slug as provided by the user
+                 */
+                original_slug: string;
+                /**
+                 * Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)
+                 */
+                slug: string;
+                output_schema?: {
+                    [key: string]: unknown;
+                };
+            }
+        }
+        interface CustomTool {
+            description: string;
+            input_schema: {
+                [key: string]: unknown;
+            };
+            name: string;
+            /**
+             * Original tool slug as provided by the user
+             */
+            original_slug: string;
+            /**
+             * Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
+             */
+            slug: string;
+            extends_toolkit?: string;
+            output_schema?: {
+                [key: string]: unknown;
+            };
+        }
+    }
+    interface Warning {
+        /**
+         * Stable machine code identifying the advisory. Safe to switch on in client code.
+         */
+        code: 'PRELOAD_TOOLS_HIGH_CONTEXT_USAGE';
+        /**
+         * Human-readable description of the advisory. Suitable for logging or surfacing to
+         * end users.
+         */
+        message: string;
+    }
+}
+export interface SessionConfigHistoryResponse {
+    current_page: number;
+    items: Array<SessionConfigHistoryResponse.Item>;
+    total_items: number;
+    total_pages: number;
+    next_cursor?: string | null;
+}
+export declare namespace SessionConfigHistoryResponse {
+    interface Item {
+        /**
+         * The session configuration at this version
+         */
+        config: Item.Config;
+        /**
+         * ISO timestamp. For history rows, when the entry was archived (i.e. the moment
+         * the version was superseded by a PATCH).
+         */
+        created_at: string;
+        /**
+         * True only for the live (current) session config, present on the first page.
+         * False for archived history rows.
+         */
+        is_current: boolean;
+        /**
+         * The config version this entry represents
+         */
+        version: number;
+    }
+    namespace Item {
+        /**
+         * The session configuration at this version
+         */
+        interface Config {
+            /**
+             * Execute helper configuration
+             */
+            execute: Config.Execute;
+            /**
+             * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+             * is returned as "all".
+             */
+            preload: Config.Preload;
+            /**
+             * Search helper configuration
+             */
+            search: Config.Search;
+            /**
+             * User identifier for this session
+             */
+            user_id: string;
+            /**
+             * Auth config overrides per toolkit
+             */
+            auth_configs?: {
+                [key: string]: string;
+            };
+            /**
+             * Connected account overrides per toolkit. Each connected account must belong to
+             * the same user_id as the session.
+             */
+            connected_accounts?: {
+                [key: string]: string;
+            };
+            /**
+             * Manage connections configuration
+             */
+            manage_connections?: Config.ManageConnections;
+            /**
+             * Multi-account configuration for this session.
+             */
+            multi_account?: Config.MultiAccount;
+            /**
+             * MCP tool annotation hints for filtering tools with enabled/disabled support.
+             * enabled: tags that the tool must have at least one of. disabled: tags that the
+             * tool must NOT have any of. Both conditions must be satisfied.
+             */
+            tags?: Config.Tags;
+            /**
+             * Toolkit configuration - either enabled list or disabled list
+             */
+            toolkits?: Config.Enabled | Config.Disabled;
+            /**
+             * Tool-level configuration per toolkit
+             */
+            tools?: {
+                [key: string]: Config.Enabled | Config.Disabled | Config.Tags;
+            };
+            /**
+             * Workbench configuration
+             */
+            workbench?: Config.Workbench;
+        }
+        namespace Config {
+            /**
+             * Execute helper configuration
+             */
+            interface Execute {
+                enable_multi_execute?: boolean;
+            }
+            /**
+             * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+             * is returned as "all".
+             */
+            interface Preload {
+                /**
+                 * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+                 * app tools allowed by its filters.
+                 */
+                tools: Array<string> | 'all';
+            }
+            /**
+             * Search helper configuration
+             */
+            interface Search {
+                enable?: boolean;
+            }
+            /**
+             * Manage connections configuration
+             */
+            interface ManageConnections {
+                /**
+                 * Custom callback URL for connected account auth flows
+                 */
+                callback_url?: string;
+                /**
+                 * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
+                 */
+                enable_connection_removal?: boolean;
+                /**
+                 * Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status.
+                 * Default false. May not work reliably with GPT models.
+                 */
+                enable_wait_for_connections?: boolean;
+                /**
+                 * Whether to enable the connection manager for automatic connection handling
+                 */
+                enabled?: boolean;
+            }
+            /**
+             * Multi-account configuration for this session.
+             */
+            interface MultiAccount {
+                /**
+                 * When true, enables multi-account mode for this session. When not set, falls back
+                 * to org/project-level configuration.
+                 */
+                enable?: boolean;
+                /**
+                 * Maximum number of connected accounts allowed per toolkit. Defaults to 5 when
+                 * multi-account is enabled.
+                 */
+                max_accounts_per_toolkit?: number;
+                /**
+                 * When true, require explicit account selection when multiple accounts are
+                 * connected. When false (default), use the first/default account.
+                 */
+                require_explicit_selection?: boolean;
+            }
+            /**
+             * MCP tool annotation hints for filtering tools with enabled/disabled support.
+             * enabled: tags that the tool must have at least one of. disabled: tags that the
+             * tool must NOT have any of. Both conditions must be satisfied.
+             */
+            interface Tags {
+                /**
+                 * Tags that the tool must NOT have any of
+                 */
+                disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+                /**
+                 * Tags that the tool must have at least one of
+                 */
+                enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            }
+            interface Enabled {
+                enabled: Array<string>;
+            }
+            interface Disabled {
+                disabled: Array<string>;
+            }
+            interface Enabled {
+                enabled: Array<string>;
+            }
+            interface Disabled {
+                disabled: Array<string>;
+            }
+            interface Tags {
+                tags: Tags.Tags;
+            }
+            namespace Tags {
+                interface Tags {
+                    /**
+                     * Tags that the tool must NOT have any of
+                     */
+                    disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+                    /**
+                     * Tags that the tool must have at least one of
+                     */
+                    enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+                }
+            }
+            /**
+             * Workbench configuration
+             */
+            interface Workbench {
+                /**
+                 * Character threshold after which tool execution response are saved to a file in
+                 * workbench. Default is 20k.
+                 */
+                auto_offload_threshold?: number;
+                /**
+                 * Whether the workbench (code execution sandbox) is enabled. When false,
+                 * COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
+                 */
+                enable?: boolean;
+                /**
+                 * Whether proxy execution is enabled in the workbench
+                 */
+                proxy_execution_enabled?: boolean;
+                /**
+                 * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
+                 * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+                 */
+                sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
+            }
+        }
+    }
+}
+export interface SessionExecuteResponse {
+    /**
+     * 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 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
+     */
+    connected_account_id: string;
+    /**
+     * Token used to complete the authentication flow
+     */
+    link_token: string;
+    /**
+     * The URL where users should be redirected to complete OAuth
+     */
+    redirect_url: string;
+}
+export interface SessionPatchResponse {
+    /**
+     * The configuration used to create this session
+     */
+    config: SessionPatchResponse.Config;
+    /**
+     * Monotonic version of the config. Incremented on each PATCH. Use for optimistic
+     * concurrency control.
+     */
+    config_version: number;
+    mcp: SessionPatchResponse.Mcp;
+    /**
+     * The identifier of the session
+     */
+    session_id: string;
+    /**
+     * List of available tools in this session
+     */
+    tool_router_tools: Array<string>;
+    /**
+     * Experimental features
+     */
+    experimental?: SessionPatchResponse.Experimental;
+    /**
+     * Advisory list — the session exists and is usable, but the listed issues may
+     * warrant attention.
+     */
+    warnings?: Array<SessionPatchResponse.Warning>;
+}
+export declare namespace SessionPatchResponse {
+    /**
+     * The configuration used to create this session
+     */
+    interface Config {
+        /**
+         * Execute helper configuration
+         */
+        execute: Config.Execute;
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
+         */
+        preload: Config.Preload;
+        /**
+         * Search helper configuration
+         */
+        search: Config.Search;
+        /**
+         * User identifier for this session
+         */
+        user_id: string;
+        /**
+         * Auth config overrides per toolkit
+         */
+        auth_configs?: {
+            [key: string]: string;
+        };
+        /**
+         * Connected account overrides per toolkit. Each connected account must belong to
+         * the same user_id as the session.
+         */
+        connected_accounts?: {
+            [key: string]: string;
+        };
+        /**
+         * Manage connections configuration
+         */
+        manage_connections?: Config.ManageConnections;
+        /**
+         * Multi-account configuration for this session.
+         */
+        multi_account?: Config.MultiAccount;
+        /**
+         * MCP tool annotation hints for filtering tools with enabled/disabled support.
+         * enabled: tags that the tool must have at least one of. disabled: tags that the
+         * tool must NOT have any of. Both conditions must be satisfied.
+         */
+        tags?: Config.Tags;
+        /**
+         * Toolkit configuration - either enabled list or disabled list
+         */
+        toolkits?: Config.Enabled | Config.Disabled;
+        /**
+         * Tool-level configuration per toolkit
+         */
+        tools?: {
+            [key: string]: Config.Enabled | Config.Disabled | Config.Tags;
+        };
+        /**
+         * Workbench configuration
+         */
+        workbench?: Config.Workbench;
+    }
+    namespace Config {
+        /**
+         * Execute helper configuration
+         */
+        interface Execute {
+            enable_multi_execute?: boolean;
+        }
+        /**
+         * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+         * is returned as "all".
+         */
+        interface Preload {
+            /**
+             * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+             * app tools allowed by its filters.
+             */
+            tools: Array<string> | 'all';
+        }
+        /**
+         * Search helper configuration
+         */
+        interface Search {
+            enable?: boolean;
+        }
+        /**
+         * Manage connections configuration
+         */
+        interface ManageConnections {
+            /**
+             * Custom callback URL for connected account auth flows
+             */
+            callback_url?: string;
+            /**
+             * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
+             */
+            enable_connection_removal?: boolean;
+            /**
+             * Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status.
+             * Default false. May not work reliably with GPT models.
+             */
+            enable_wait_for_connections?: boolean;
+            /**
+             * Whether to enable the connection manager for automatic connection handling
+             */
+            enabled?: boolean;
+        }
+        /**
+         * Multi-account configuration for this session.
+         */
+        interface MultiAccount {
+            /**
+             * When true, enables multi-account mode for this session. When not set, falls back
+             * to org/project-level configuration.
+             */
+            enable?: boolean;
+            /**
+             * Maximum number of connected accounts allowed per toolkit. Defaults to 5 when
+             * multi-account is enabled.
+             */
+            max_accounts_per_toolkit?: number;
+            /**
+             * When true, require explicit account selection when multiple accounts are
+             * connected. When false (default), use the first/default account.
+             */
+            require_explicit_selection?: boolean;
+        }
+        /**
+         * MCP tool annotation hints for filtering tools with enabled/disabled support.
+         * enabled: tags that the tool must have at least one of. disabled: tags that the
+         * tool must NOT have any of. Both conditions must be satisfied.
+         */
+        interface Tags {
+            /**
+             * Tags that the tool must NOT have any of
+             */
+            disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            /**
+             * Tags that the tool must have at least one of
+             */
+            enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        interface Enabled {
+            enabled: Array<string>;
+        }
+        interface Disabled {
+            disabled: Array<string>;
+        }
+        interface Tags {
+            tags: Tags.Tags;
+        }
+        namespace Tags {
+            interface Tags {
+                /**
+                 * Tags that the tool must NOT have any of
+                 */
+                disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+                /**
+                 * Tags that the tool must have at least one of
+                 */
+                enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            }
+        }
+        /**
+         * Workbench configuration
+         */
+        interface Workbench {
+            /**
+             * Character threshold after which tool execution response are saved to a file in
+             * workbench. Default is 20k.
+             */
+            auto_offload_threshold?: number;
+            /**
+             * Whether the workbench (code execution sandbox) is enabled. When false,
+             * COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
+             */
+            enable?: boolean;
+            /**
+             * Whether proxy execution is enabled in the workbench
+             */
+            proxy_execution_enabled?: boolean;
+            /**
+             * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
+             * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+             */
+            sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
+        }
+    }
+    interface Mcp {
+        /**
+         * The type of the MCP server. Can be http
+         */
+        type: 'http';
+        /**
+         * The URL of the MCP server
+         */
+        url: string;
+    }
+    /**
+     * Experimental features
+     */
+    interface Experimental {
+        /**
+         * The assistive system prompt for the tool router session
+         */
+        assistive_prompt?: string;
+        /**
+         * User-defined custom toolkits with grouped tools (no-auth)
+         */
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
+        /**
+         * Custom tools — standalone or extending Composio toolkits
+         */
+        custom_tools?: Array<Experimental.CustomTool>;
+    }
+    namespace Experimental {
+        interface CustomToolkit {
+            description: string;
+            name: string;
+            slug: string;
+            tools: Array<CustomToolkit.Tool>;
+        }
+        namespace CustomToolkit {
+            interface Tool {
+                description: string;
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                name: string;
+                /**
+                 * Original tool slug as provided by the user
+                 */
+                original_slug: string;
+                /**
+                 * Prefixed tool slug (e.g. LOCAL_CRM_FIND_CUSTOMER)
+                 */
+                slug: string;
+                output_schema?: {
+                    [key: string]: unknown;
+                };
+            }
+        }
+        interface CustomTool {
+            description: string;
+            input_schema: {
+                [key: string]: unknown;
+            };
+            name: string;
+            /**
+             * Original tool slug as provided by the user
+             */
+            original_slug: string;
+            /**
+             * Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
+             */
+            slug: string;
+            extends_toolkit?: string;
+            output_schema?: {
+                [key: string]: unknown;
+            };
+        }
+    }
+    interface Warning {
+        /**
+         * Stable machine code identifying the advisory. Safe to switch on in client code.
+         */
+        code: 'PRELOAD_TOOLS_HIGH_CONTEXT_USAGE';
+        /**
+         * Human-readable description of the advisory. Suitable for logging or surfacing to
+         * end users.
+         */
+        message: string;
+    }
+}
+export interface SessionProxyExecuteResponse {
+    /**
+     * The HTTP status code returned from the proxied API
+     */
+    status: number;
+    /**
+     * Binary body response data. Present when the response is a binary file.
+     */
+    binary_data?: SessionProxyExecuteResponse.BinaryData;
+    /**
+     * The response data returned from the proxied API
+     */
+    data?: unknown;
+    /**
+     * The HTTP headers returned from the proxied API
+     */
+    headers?: {
+        [key: string]: string;
+    };
+}
+export declare namespace SessionProxyExecuteResponse {
+    /**
+     * Binary body response data. Present when the response is a binary file.
+     */
+    interface BinaryData {
+        /**
+         * Content-Type of the binary data
+         */
+        content_type: string;
+        /**
+         * File size in bytes
+         */
+        size: number;
+        /**
+         * URL to download binary content
+         */
+        url: string;
+        /**
+         * ISO 8601 timestamp when the URL expires
+         */
+        expires_at?: string;
+    }
+}
+export interface SessionSearchResponse {
+    /**
+     * Error message if any searches failed, null if all succeeded. Format: "X out of Y
+     * searches failed, reasons: <details>"
+     */
+    error: string | null;
+    /**
+     * Combined workflow guidance covering connections, planner, and memory usage. Each
+     * element is a step instruction.
+     */
+    next_steps_guidance: Array<string>;
+    /**
+     * Per-query search results with tools, reasoning, and memory. One entry per query
+     * in request order.
+     */
+    results: Array<SessionSearchResponse.Result>;
+    /**
+     * Session info for correlating meta tool calls
+     */
+    session: SessionSearchResponse.Session;
+    /**
+     * Whether all searches completed successfully. False if any query failed.
+     */
+    success: boolean;
+    /**
+     * Time information for the query
+     */
+    time_info: SessionSearchResponse.TimeInfo;
+    /**
+     * Deduplicated tool definitions keyed by tool_slug for O(1) lookup. Each tool
+     * appears once even if used in multiple queries.
+     */
+    tool_schemas: {
+        [key: string]: SessionSearchResponse.ToolSchemas;
+    };
+    /**
+     * Connection status for all toolkits mentioned across all queries, with
+     * descriptions merged in.
+     */
+    toolkit_connection_statuses: Array<SessionSearchResponse.ToolkitConnectionStatus>;
+}
+export declare namespace SessionSearchResponse {
+    interface Result {
+        /**
+         * 1-based index of the query in the request
+         */
+        index: number;
+        /**
+         * List of main tool slugs matching the search criteria
+         */
+        primary_tool_slugs: Array<string>;
+        /**
+         * List of related tool slugs that might be useful
+         */
+        related_tool_slugs: Array<string>;
+        /**
+         * List of unique toolkit slugs used by tools in this query
+         */
+        toolkits: Array<string>;
+        /**
+         * The use case that was searched
+         */
+        use_case: string;
+        /**
+         * Task difficulty assessment (e.g., "easy - Simple single-tool operation with
+         * known parameters")
+         */
+        difficulty?: string;
+        /**
+         * Error message if the search for this query failed, null otherwise. Always
+         * present for failed queries.
+         */
+        error?: string | null;
+        /**
+         * Guidance message about the search results, particularly when a cached plan is
+         * available
+         */
+        execution_guidance?: string;
+        /**
+         * Common pitfalls and considerations (only present when cached plan is available)
+         */
+        known_pitfalls?: Array<string>;
+        /**
+         * Memory data relevant to this query, grouped by app. Only present for non-cached
+         * search results.
+         */
+        memory?: {
+            [key: string]: Array<string>;
+        };
+        /**
+         * ID of cached plan if available
+         */
+        plan_id?: string;
+        /**
+         * Workflow steps from cached plan (only present when cached plan is available)
+         */
+        recommended_plan_steps?: Array<string>;
+        /**
+         * Reference Python code snippets for processing tool responses in the workbench
+         * (only present when cached plan is available)
+         */
+        reference_workbench_snippets?: Array<Result.ReferenceWorkbenchSnippet>;
+    }
+    namespace Result {
+        interface ReferenceWorkbenchSnippet {
+            /**
+             * Python code snippet for the workbench
+             */
+            code: string;
+            /**
+             * Description of what the code snippet does
+             */
+            description: string;
+        }
+    }
+    /**
+     * Session info for correlating meta tool calls
+     */
+    interface Session {
+        /**
+         * Session identifier to be passed to subsequent meta tool calls as session_id.
+         */
+        id: string;
+        /**
+         * Whether a fresh session id was generated in this call.
+         */
+        generate_id: boolean;
         /**
          * LLM-facing guidance on how to reuse this session id
          */
@@ -1059,381 +1963,932 @@ export declare namespace SessionSearchResponse {
         /**
          * Description of what the toolkit does and its capabilities
          */
-        description: string;
+        description: string;
+        /**
+         * Whether an active connection exists for this toolkit
+         */
+        has_active_connection: boolean;
+        /**
+         * Human-readable message about the connection status and next steps
+         */
+        status_message: string;
+        /**
+         * The toolkit slug identifier (e.g., "gmail", "slack")
+         */
+        toolkit: string;
+        /**
+         * When "required", the agent must specify which account to use. Present only when
+         * multiple accounts exist.
+         */
+        account_selection?: 'required';
+        /**
+         * List of connected accounts for this toolkit. Present when multi-account is
+         * enabled.
+         */
+        accounts?: Array<ToolkitConnectionStatus.Account>;
+        /**
+         * Connection details including auth config and connected account IDs. Only present
+         * when has_active_connection is true.
+         */
+        connection_details?: {
+            [key: string]: unknown;
+        };
+        /**
+         * Information about the currently connected user (email, name, etc.)
+         */
+        current_user_info?: {
+            [key: string]: unknown;
+        };
+    }
+    namespace ToolkitConnectionStatus {
+        interface Account {
+            /**
+             * Unique identifier for this account
+             */
+            id: string;
+            /**
+             * ISO 8601 timestamp of when the account was connected
+             */
+            created_at: string;
+            /**
+             * Whether this is the default account for the toolkit
+             */
+            is_default: boolean;
+            /**
+             * Connection status (e.g., "active")
+             */
+            status: string;
+            /**
+             * User-assigned alias for this account
+             */
+            alias?: string;
+            /**
+             * Information about the connected user (email, name, etc.)
+             */
+            user_info?: {
+                [key: string]: unknown;
+            };
+        }
+    }
+}
+export interface SessionToolkitsResponse {
+    current_page: number;
+    items: Array<SessionToolkitsResponse.Item>;
+    total_items: number;
+    total_pages: number;
+    next_cursor?: string | null;
+}
+export declare namespace SessionToolkitsResponse {
+    interface Item {
+        /**
+         * Available Composio-managed auth schemes
+         */
+        composio_managed_auth_schemes: Array<string>;
+        /**
+         * Connected account if available
+         */
+        connected_account: Item.ConnectedAccount | null;
+        /**
+         * Whether the toolkit is enabled
+         */
+        enabled: boolean;
+        /**
+         * Whether the toolkit is no-auth
+         */
+        is_no_auth: boolean;
+        /**
+         * Toolkit metadata
+         */
+        meta: Item.Meta;
+        /**
+         * Display name of the toolkit
+         */
+        name: string;
+        /**
+         * Unique slug identifier
+         */
+        slug: string;
+    }
+    namespace Item {
+        /**
+         * Connected account if available
+         */
+        interface ConnectedAccount {
+            /**
+             * Connected account identifier
+             */
+            id: string;
+            /**
+             * Auth config details
+             */
+            auth_config: ConnectedAccount.AuthConfig;
+            /**
+             * Creation timestamp
+             */
+            created_at: string;
+            /**
+             * Connection status
+             */
+            status: string;
+            /**
+             * User identifier
+             */
+            user_id: string;
+        }
+        namespace ConnectedAccount {
+            /**
+             * Auth config details
+             */
+            interface AuthConfig {
+                /**
+                 * Auth config identifier
+                 */
+                id: string;
+                /**
+                 * Authentication scheme type
+                 */
+                auth_scheme: string;
+                /**
+                 * Whether this is a Composio-managed auth config
+                 */
+                is_composio_managed: boolean;
+            }
+        }
+        /**
+         * Toolkit metadata
+         */
+        interface Meta {
+            /**
+             * Description of the toolkit
+             */
+            description: string;
+            /**
+             * URL to the toolkit logo
+             */
+            logo: string;
+        }
+    }
+}
+export interface SessionToolsResponse {
+    current_page: number;
+    items: Array<SessionToolsResponse.Item>;
+    total_items: number;
+    total_pages: number;
+    next_cursor?: string | null;
+}
+export declare namespace SessionToolsResponse {
+    interface Item {
+        /**
+         * List of all available versions for this tool
+         */
+        available_versions: Array<string>;
+        deprecated: Item.Deprecated;
+        /**
+         * Detailed explanation of the tool's functionality and purpose
+         */
+        description: string;
+        /**
+         * Schema definition of required input parameters for the tool
+         */
+        input_parameters: {
+            [key: string]: unknown;
+        };
+        /**
+         * Indicates if this tool is deprecated and may be removed in the future
+         */
+        is_deprecated: boolean;
+        /**
+         * Human-readable display name of the tool
+         */
+        name: string;
+        /**
+         * Indicates if the tool can be used without authentication
+         */
+        no_auth: boolean;
         /**
-         * Whether an active connection exists for this toolkit
+         * Schema definition of return values from the tool
          */
-        has_active_connection: boolean;
+        output_parameters: {
+            [key: string]: unknown;
+        };
         /**
-         * Human-readable message about the connection status and next steps
+         * Structured scope requirements for the tool. Null means the tool is legacy and
+         * only exposes flat scopes.
          */
-        status_message: string;
+        scope_requirements: Item.ScopeRequirements | null;
         /**
-         * The toolkit slug identifier (e.g., "gmail", "slack")
+         * List of scopes associated with the tool
          */
-        toolkit: string;
+        scopes: Array<string>;
         /**
-         * When "required", the agent must specify which account to use. Present only when
-         * multiple accounts exist.
+         * Unique identifier for the tool
          */
-        account_selection?: 'required';
+        slug: string;
         /**
-         * List of connected accounts for this toolkit. Present when multi-account is
-         * enabled.
+         * List of tags associated with the tool for categorization and filtering
          */
-        accounts?: Array<ToolkitConnectionStatus.Account>;
+        tags: Array<string>;
+        toolkit: Item.Toolkit;
         /**
-         * Connection details including auth config and connected account IDs. Only present
-         * when has_active_connection is true.
+         * Current version of the tool
          */
-        connection_details?: {
-            [key: string]: unknown;
-        };
+        version: string;
         /**
-         * Information about the currently connected user (email, name, etc.)
+         * Human-friendly description of the tool, if available
          */
-        current_user_info?: {
-            [key: string]: unknown;
-        };
+        human_description?: string;
     }
-    namespace ToolkitConnectionStatus {
-        interface Account {
+    namespace Item {
+        interface Deprecated {
             /**
-             * Unique identifier for this account
+             * List of all available versions for this tool
              */
-            id: string;
+            available_versions: Array<string>;
             /**
-             * ISO 8601 timestamp of when the account was connected
+             * The display name of the tool
              */
-            created_at: string;
+            displayName: string;
             /**
-             * Whether this is the default account for the toolkit
+             * Indicates if this tool is deprecated and may be removed in the future
              */
-            is_default: boolean;
+            is_deprecated: boolean;
+            toolkit: Deprecated.Toolkit;
             /**
-             * Connection status (e.g., "active")
+             * Current version identifier of the tool
              */
-            status: string;
+            version: string;
+        }
+        namespace Deprecated {
+            interface Toolkit {
+                /**
+                 * URL to the toolkit logo image
+                 */
+                logo: string;
+            }
+        }
+        /**
+         * Structured scope requirements for the tool. Null means the tool is legacy and
+         * only exposes flat scopes.
+         */
+        interface ScopeRequirements {
+            all_of: Array<string | ScopeRequirements.AnyOf>;
+        }
+        namespace ScopeRequirements {
+            interface AnyOf {
+                any_of: Array<string>;
+            }
+        }
+        interface Toolkit {
             /**
-             * User-assigned alias for this account
+             * URL to the toolkit logo image
              */
-            alias?: string;
+            logo: string;
             /**
-             * Information about the connected user (email, name, etc.)
+             * Human-readable name of the parent toolkit
              */
-            user_info?: {
-                [key: string]: unknown;
-            };
+            name: string;
+            /**
+             * Unique identifier of the parent toolkit
+             */
+            slug: string;
         }
     }
 }
-export interface SessionToolkitsResponse {
-    current_page: number;
-    items: Array<SessionToolkitsResponse.Item>;
-    total_items: number;
-    total_pages: number;
-    next_cursor?: string | null;
+export interface SessionCreateParams {
+    /**
+     * The identifier of the user who is initiating the session, ideally a unique
+     * identifier from your database like a user ID or email address
+     */
+    user_id: string;
+    /**
+     * The auth configs to use for the session. This will override the default behavior
+     * and use the given auth config when specific toolkits are being executed
+     */
+    auth_configs?: {
+        [key: string]: string;
+    };
+    /**
+     * The connected accounts to use for the session. This will override the default
+     * behaviour and use the given connected account when specific toolkits are being
+     * executed. Each connected account must exist (not deleted or disabled) and belong
+     * to the same `user_id` as the session — otherwise session creation fails with a
+     * clear error explaining which account didn't match.
+     */
+    connected_accounts?: {
+        [key: string]: string;
+    };
+    execute?: SessionCreateParams.Execute;
+    /**
+     * Experimental features - not stable, may be modified or removed in future
+     * versions.
+     */
+    experimental?: SessionCreateParams.Experimental;
+    /**
+     * Configuration for connection management settings
+     */
+    manage_connections?: SessionCreateParams.ManageConnections;
+    /**
+     * Configure multi-account behavior. When enabled, users can connect multiple
+     * accounts per toolkit.
+     */
+    multi_account?: SessionCreateParams.MultiAccount;
+    /**
+     * Preload configuration. Use an explicit list for frequently used tool slugs, or
+     * "all" to dynamically expose every app tool allowed by positive
+     * toolkits/tools/tags filters.
+     */
+    preload?: SessionCreateParams.Preload;
+    search?: SessionCreateParams.Search;
+    /**
+     * Global MCP tool annotation hints for filtering. Array format is treated as
+     * enabled list. Object format supports both enabled (tool must have at least one)
+     * and disabled (tool must NOT have any) lists. Toolkit-level tags override this.
+     * Toolkit enabled/disabled lists take precedence over tag filtering.
+     */
+    tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'> | SessionCreateParams.UnionMember1;
+    /**
+     * Toolkit configuration - specify either enable toolkits (allowlist) or disable
+     * toolkits (denylist). Mutually exclusive.
+     */
+    toolkits?: SessionCreateParams.Enable | SessionCreateParams.Disable;
+    /**
+     * Tool-level configuration per toolkit. Allows you to enable, disable, or filter
+     * by tags for specific tools within each toolkit. Every slug passed in `enable` /
+     * `disable` must be a valid Composio tool slug for that toolkit — invalid or
+     * typo'd slugs fail session creation with a clear error listing which ones didn't
+     * match.
+     */
+    tools?: {
+        [key: string]: SessionCreateParams.Enable | SessionCreateParams.Disable | SessionCreateParams.Tags;
+    };
+    /**
+     * Configuration for workbench behavior
+     */
+    workbench?: SessionCreateParams.Workbench;
 }
-export declare namespace SessionToolkitsResponse {
-    interface Item {
-        /**
-         * Available Composio-managed auth schemes
-         */
-        composio_managed_auth_schemes: Array<string>;
-        /**
-         * Connected account if available
-         */
-        connected_account: Item.ConnectedAccount | null;
-        /**
-         * Whether the toolkit is enabled
-         */
-        enabled: boolean;
+export declare namespace SessionCreateParams {
+    interface Execute {
+        enable_multi_execute?: boolean;
+    }
+    /**
+     * Experimental features - not stable, may be modified or removed in future
+     * versions.
+     */
+    interface Experimental {
         /**
-         * Whether the toolkit is no-auth
+         * Customize assistive prompt generation (e.g., timezone).
          */
-        is_no_auth: boolean;
+        assistive_prompt_config?: Experimental.AssistivePromptConfig;
         /**
-         * Toolkit metadata
+         * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+         * existing Composio toolkits. All tools are no-auth.
          */
-        meta: Item.Meta;
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
         /**
-         * Display name of the toolkit
+         * Custom tools to include in search. Standalone tools need no auth. Tools with
+         * extends_toolkit inherit the Composio toolkit's connection.
          */
-        name: string;
+        custom_tools?: Array<Experimental.CustomTool>;
         /**
-         * Unique slug identifier
+         * Per-tool elicitation permission config. Default behavior + per-tool
+         * always_allow/always_deny overrides. Mutation via PATCH.
          */
-        slug: string;
+        permissions?: Experimental.Permissions;
     }
-    namespace Item {
+    namespace Experimental {
         /**
-         * Connected account if available
+         * Customize assistive prompt generation (e.g., timezone).
          */
-        interface ConnectedAccount {
+        interface AssistivePromptConfig {
+            /**
+             * IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to
+             * customize the system prompt with timezone-aware instructions.
+             */
+            user_timezone?: string;
+        }
+        interface CustomToolkit {
+            /**
+             * Used for BM25 search matching and shown in toolkit connection statuses.
+             */
+            description: string;
+            /**
+             * Display name shown to the LLM and in search results.
+             */
+            name: string;
+            /**
+             * Unique slug for the toolkit. Must not conflict with existing Composio toolkit
+             * slugs. Alphanumeric, underscores, and hyphens only.
+             */
+            slug: string;
+            /**
+             * Tools in this custom toolkit
+             */
+            tools: Array<CustomToolkit.Tool>;
+        }
+        namespace CustomToolkit {
+            interface Tool {
+                /**
+                 * Used for BM25 search matching and shown to the LLM.
+                 */
+                description: string;
+                /**
+                 * Must have type: "object" and a properties field.
+                 */
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                /**
+                 * Human-readable display name
+                 */
+                name: string;
+                /**
+                 * Tool slug. Combined with toolkit slug to form LOCAL*<TOOLKIT>*<TOOL> (max 60
+                 * chars total).
+                 */
+                slug: string;
+                /**
+                 * Optional output schema for the tool response.
+                 */
+                output_schema?: {
+                    [key: string]: unknown;
+                };
+            }
+        }
+        interface CustomTool {
             /**
-             * Connected account identifier
+             * Used for BM25 search matching and shown to the LLM.
              */
-            id: string;
+            description: string;
             /**
-             * Auth config details
+             * Must have type: "object" and a properties field.
              */
-            auth_config: ConnectedAccount.AuthConfig;
+            input_schema: {
+                [key: string]: unknown;
+            };
             /**
-             * Creation timestamp
+             * Human-readable display name
              */
-            created_at: string;
+            name: string;
             /**
-             * Connection status
+             * Tool slug. Forms LOCAL*<TOOL> (standalone) or LOCAL*<TOOLKIT>\_<TOOL>
+             * (extending). Max 60 chars total.
              */
-            status: string;
+            slug: string;
             /**
-             * User identifier
+             * If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's
+             * auth/connection status. If omitted, the tool is standalone (no-auth).
              */
-            user_id: string;
-        }
-        namespace ConnectedAccount {
+            extends_toolkit?: string;
             /**
-             * Auth config details
+             * JSON Schema describing tool output (optional)
              */
-            interface AuthConfig {
-                /**
-                 * Auth config identifier
-                 */
-                id: string;
-                /**
-                 * Authentication scheme type
-                 */
-                auth_scheme: string;
-                /**
-                 * Whether this is a Composio-managed auth config
-                 */
-                is_composio_managed: boolean;
-            }
+            output_schema?: {
+                [key: string]: unknown;
+            };
         }
         /**
-         * Toolkit metadata
+         * Per-tool elicitation permission config. Default behavior + per-tool
+         * always_allow/always_deny overrides. Mutation via PATCH.
          */
-        interface Meta {
+        interface Permissions {
             /**
-             * Description of the toolkit
+             * Default elicitation behavior when no override matches. `allow_all` runs every
+             * tool without prompting; `ask_every_call` prompts on each invocation;
+             * `ask_once_per_session` prompts once and remembers the answer for the rest of the
+             * session.
              */
-            description: string;
+            default: 'allow_all' | 'ask_every_call' | 'ask_once_per_session';
             /**
-             * URL to the toolkit logo
+             * Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? "__none__"}`,
+             * plus account-wide overrides keyed by `*:${connectedAccountId ?? "__none__"}`.
+             * Exact tool overrides take precedence over account-wide overrides. `always_allow`
+             * skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once`
+             * prompts once per session (allow/deny) and remembers; `ask_always` prompts on
+             * every call with allow-once/allow-session/deny, ignoring any cached session
+             * allow. Overrides take precedence over `default`.
              */
-            logo: string;
+            overrides?: {
+                [key: string]: 'always_allow' | 'always_deny' | 'ask_once' | 'ask_always';
+            };
         }
     }
-}
-export interface SessionToolsResponse {
     /**
-     * List of tools with their complete schemas
+     * Configuration for connection management settings
      */
-    items: Array<SessionToolsResponse.Item>;
-}
-export declare namespace SessionToolsResponse {
-    interface Item {
+    interface ManageConnections {
         /**
-         * List of all available versions for this tool
+         * 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.
          */
-        available_versions: Array<string>;
-        deprecated: Item.Deprecated;
+        callback_url?: string;
         /**
-         * Detailed explanation of the tool's functionality and purpose
+         * 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.
          */
-        description: string;
+        enable?: boolean | null;
         /**
-         * Schema definition of required input parameters for the tool
+         * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting
+         * connected accounts. Default true.
          */
-        input_parameters: {
-            [key: string]: unknown;
-        };
+        enable_connection_removal?: boolean | null;
         /**
-         * Indicates if this tool is deprecated and may be removed in the future
+         * When true, the COMPOSIO_WAIT_FOR_CONNECTIONS tool is available for agents to
+         * poll connection status after sharing auth URLs. Default is false (disabled). May
+         * not work reliably with GPT models.
          */
-        is_deprecated: boolean;
+        enable_wait_for_connections?: boolean | null;
+    }
+    /**
+     * Configure multi-account behavior. When enabled, users can connect multiple
+     * accounts per toolkit.
+     */
+    interface MultiAccount {
         /**
-         * Human-readable display name of the tool
+         * When true, enables multi-account mode for this session. When not set, falls back
+         * to org/project-level configuration.
          */
-        name: string;
+        enable?: boolean;
         /**
-         * Indicates if the tool can be used without authentication
+         * Maximum number of connected accounts allowed per toolkit. Must be between 2
+         * and 10.
          */
-        no_auth: boolean;
+        max_accounts_per_toolkit?: number;
         /**
-         * Schema definition of return values from the tool
+         * When true, the agent must explicitly select which account to use. When false
+         * (default), the first/default account is used automatically.
          */
-        output_parameters: {
-            [key: string]: unknown;
-        };
+        require_explicit_selection?: boolean;
+    }
+    /**
+     * Preload configuration. Use an explicit list for frequently used tool slugs, or
+     * "all" to dynamically expose every app tool allowed by positive
+     * toolkits/tools/tags filters.
+     */
+    interface Preload {
         /**
-         * Structured scope requirements for the tool. Null means the tool is legacy and
-         * only exposes flat scopes.
+         * Explicit tool slugs to preload, or "all" to dynamically expose all current and
+         * future app tools allowed by the positive session filters. "all" is capped at
+         * 1000 tools and is not supported without a positive allowlist.
          */
-        scope_requirements: Item.ScopeRequirements | null;
+        tools?: Array<string> | string;
+    }
+    interface Search {
+        enable?: boolean;
+    }
+    interface UnionMember1 {
+        disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+        enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+    }
+    /**
+     * Enable only specific toolkits (allowlist)
+     */
+    interface Enable {
         /**
-         * List of scopes associated with the tool
+         * Only these specific toolkits will be enabled
          */
-        scopes: Array<string>;
+        enable: Array<string>;
+    }
+    /**
+     * Disable specific toolkits (denylist)
+     */
+    interface Disable {
         /**
-         * Unique identifier for the tool
+         * These specific toolkits will be disabled
          */
-        slug: string;
+        disable: Array<string>;
+    }
+    interface Enable {
         /**
-         * List of tags associated with the tool for categorization and filtering
+         * Only these specific tools will be available for this toolkit
          */
-        tags: Array<string>;
-        toolkit: Item.Toolkit;
+        enable: Array<string>;
+    }
+    interface Disable {
         /**
-         * Current version of the tool
+         * These specific tools will be disabled for this toolkit
          */
-        version: string;
+        disable: Array<string>;
+    }
+    interface Tags {
         /**
-         * Human-friendly description of the tool, if available
+         * MCP tags to filter tools. Array format is treated as enabled list. Object format
+         * supports both enabled and disabled lists.
          */
-        human_description?: string;
+        tags: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'> | Tags.UnionMember1;
     }
-    namespace Item {
-        interface Deprecated {
+    namespace Tags {
+        interface UnionMember1 {
+            disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+            enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+        }
+    }
+    /**
+     * Configuration for workbench behavior
+     */
+    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;
+        /**
+         * Set to false to disable the workbench entirely. When disabled, no code execution
+         * tools are available in the session.
+         */
+        enable?: boolean;
+        /**
+         * Whether proxy execution is enabled. When enabled, workbench can call URLs and
+         * APIs directly.
+         */
+        enable_proxy_execution?: boolean;
+        /**
+         * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
+         * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+         */
+        sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
+    }
+}
+export interface SessionAttachParams {
+    /**
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
+     */
+    experimental?: SessionAttachParams.Experimental;
+}
+export declare namespace SessionAttachParams {
+    /**
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
+     */
+    interface Experimental {
+        /**
+         * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+         * existing Composio toolkits. All tools are no-auth.
+         */
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
+        /**
+         * Custom tools to include in search. Standalone tools need no auth. Tools with
+         * extends_toolkit inherit the Composio toolkit's connection.
+         */
+        custom_tools?: Array<Experimental.CustomTool>;
+    }
+    namespace Experimental {
+        interface CustomToolkit {
             /**
-             * List of all available versions for this tool
+             * Used for BM25 search matching and shown in toolkit connection statuses.
              */
-            available_versions: Array<string>;
+            description: string;
             /**
-             * The display name of the tool
+             * Display name shown to the LLM and in search results.
              */
-            displayName: string;
+            name: string;
             /**
-             * Indicates if this tool is deprecated and may be removed in the future
+             * Unique slug for the toolkit. Must not conflict with existing Composio toolkit
+             * slugs. Alphanumeric, underscores, and hyphens only.
              */
-            is_deprecated: boolean;
-            toolkit: Deprecated.Toolkit;
+            slug: string;
             /**
-             * Current version identifier of the tool
+             * Tools in this custom toolkit
              */
-            version: string;
+            tools: Array<CustomToolkit.Tool>;
         }
-        namespace Deprecated {
-            interface Toolkit {
+        namespace CustomToolkit {
+            interface Tool {
                 /**
-                 * URL to the toolkit logo image
+                 * Used for BM25 search matching and shown to the LLM.
                  */
-                logo: string;
-            }
-        }
-        /**
-         * Structured scope requirements for the tool. Null means the tool is legacy and
-         * only exposes flat scopes.
-         */
-        interface ScopeRequirements {
-            all_of: Array<string | ScopeRequirements.AnyOf>;
-        }
-        namespace ScopeRequirements {
-            interface AnyOf {
-                any_of: Array<string>;
+                description: string;
+                /**
+                 * Must have type: "object" and a properties field.
+                 */
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                /**
+                 * Human-readable display name
+                 */
+                name: string;
+                /**
+                 * Tool slug. Combined with toolkit slug to form LOCAL*<TOOLKIT>*<TOOL> (max 60
+                 * chars total).
+                 */
+                slug: string;
+                /**
+                 * Optional output schema for the tool response.
+                 */
+                output_schema?: {
+                    [key: string]: unknown;
+                };
             }
         }
-        interface Toolkit {
+        interface CustomTool {
             /**
-             * URL to the toolkit logo image
+             * Used for BM25 search matching and shown to the LLM.
              */
-            logo: string;
+            description: string;
             /**
-             * Human-readable name of the parent toolkit
+             * Must have type: "object" and a properties field.
+             */
+            input_schema: {
+                [key: string]: unknown;
+            };
+            /**
+             * Human-readable display name
              */
             name: string;
             /**
-             * Unique identifier of the parent toolkit
+             * Tool slug. Forms LOCAL*<TOOL> (standalone) or LOCAL*<TOOLKIT>\_<TOOL>
+             * (extending). Max 60 chars total.
              */
             slug: string;
+            /**
+             * If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's
+             * auth/connection status. If omitted, the tool is standalone (no-auth).
+             */
+            extends_toolkit?: string;
+            /**
+             * JSON Schema describing tool output (optional)
+             */
+            output_schema?: {
+                [key: string]: unknown;
+            };
         }
     }
 }
-export interface SessionCreateParams {
+export interface SessionConfigHistoryParams {
     /**
-     * The identifier of the user who is initiating the session, ideally a unique
-     * identifier from your database like a user ID or email address
+     * Cursor for pagination. The cursor is a base64 encoded string of the page and
+     * limit. The page is the page number and the limit is the number of items per
+     * page. The cursor is used to paginate through the items. The cursor is not
+     * required for the first page.
      */
-    user_id: string;
+    cursor?: string;
     /**
-     * The auth configs to use for the session. This will override the default behavior
-     * and use the given auth config when specific toolkits are being executed
+     * Number of items per page, max allowed is 100
      */
-    auth_configs?: {
-        [key: string]: string;
-    };
+    limit?: number;
+}
+export interface SessionExecuteParams {
     /**
-     * The connected accounts to use for the session. This will override the default
-     * behaviour and use the given connected account when specific toolkits are being
-     * executed. Each connected account must exist (not deleted or disabled) and belong
-     * to the same `user_id` as the session — otherwise session creation fails with a
-     * clear error explaining which account didn't match.
+     * The unique slug identifier of the tool to execute. Supports both meta tools and
+     * app tools exposed by the session.
      */
-    connected_accounts?: {
-        [key: string]: string;
-    };
+    tool_slug: string;
     /**
-     * Experimental features - not stable, may be modified or removed in future
-     * versions.
+     * Account identifier to specify which connected account to use for direct tool
+     * execution. Use the account ID (e.g. "coup_hurricane_dal_analytical") or an
+     * alias. When omitted with a single account, the default is used. When omitted
+     * with multiple accounts, an error lists available accounts. Meta/helper tools
+     * either ignore this top-level field or define their own account-selection fields,
+     * for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.
      */
-    experimental?: SessionCreateParams.Experimental;
+    account?: string;
     /**
-     * Configuration for connection management settings
+     * The arguments required by the tool
      */
-    manage_connections?: SessionCreateParams.ManageConnections;
+    arguments?: {
+        [key: string]: unknown;
+    };
     /**
-     * Configure multi-account behavior. When enabled, users can connect multiple
-     * accounts per toolkit.
+     * When true, direct non-meta tool execution may return a workbench offload preview
+     * if the response exceeds the configured threshold and the session workbench is
+     * enabled. When omitted or false, direct tool execution returns the normal inline
+     * response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses
+     * session.workbench configuration for its own batch-level offload behavior.
      */
-    multi_account?: SessionCreateParams.MultiAccount;
+    enable_auto_workbench_offload?: boolean;
     /**
-     * Preload configuration. Controls which tools appear in `session.tools` and the
-     * MCP server tool list so the agent can call them directly without going through
-     * search first — useful for frequently used tools. Each slug must be allowed by
-     * the session filters (`toolkits`, `tools`, `tags`), otherwise session creation
-     * fails with a 400. Custom tools declared in `custom_tools` / `custom_toolkits`
-     * can also be preloaded. Not supported when multi-account is enabled. Each
-     * preloaded tool adds to the agent context window, so keep the list at or under
-     * ~20 tools.
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
      */
-    preload?: SessionCreateParams.Preload;
+    experimental?: SessionExecuteParams.Experimental;
+}
+export declare namespace SessionExecuteParams {
     /**
-     * Global MCP tool annotation hints for filtering. Array format is treated as
-     * enabled list. Object format supports both enabled (tool must have at least one)
-     * and disabled (tool must NOT have any) lists. Toolkit-level tags override this.
-     * Toolkit enabled/disabled lists take precedence over tag filtering.
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
      */
-    tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'> | SessionCreateParams.UnionMember1;
+    interface Experimental {
+        /**
+         * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+         * existing Composio toolkits. All tools are no-auth.
+         */
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
+        /**
+         * Custom tools to include in search. Standalone tools need no auth. Tools with
+         * extends_toolkit inherit the Composio toolkit's connection.
+         */
+        custom_tools?: Array<Experimental.CustomTool>;
+    }
+    namespace Experimental {
+        interface CustomToolkit {
+            /**
+             * Used for BM25 search matching and shown in toolkit connection statuses.
+             */
+            description: string;
+            /**
+             * Display name shown to the LLM and in search results.
+             */
+            name: string;
+            /**
+             * Unique slug for the toolkit. Must not conflict with existing Composio toolkit
+             * slugs. Alphanumeric, underscores, and hyphens only.
+             */
+            slug: string;
+            /**
+             * Tools in this custom toolkit
+             */
+            tools: Array<CustomToolkit.Tool>;
+        }
+        namespace CustomToolkit {
+            interface Tool {
+                /**
+                 * Used for BM25 search matching and shown to the LLM.
+                 */
+                description: string;
+                /**
+                 * Must have type: "object" and a properties field.
+                 */
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                /**
+                 * Human-readable display name
+                 */
+                name: string;
+                /**
+                 * Tool slug. Combined with toolkit slug to form LOCAL*<TOOLKIT>*<TOOL> (max 60
+                 * chars total).
+                 */
+                slug: string;
+                /**
+                 * Optional output schema for the tool response.
+                 */
+                output_schema?: {
+                    [key: string]: unknown;
+                };
+            }
+        }
+        interface CustomTool {
+            /**
+             * Used for BM25 search matching and shown to the LLM.
+             */
+            description: string;
+            /**
+             * Must have type: "object" and a properties field.
+             */
+            input_schema: {
+                [key: string]: unknown;
+            };
+            /**
+             * Human-readable display name
+             */
+            name: string;
+            /**
+             * Tool slug. Forms LOCAL*<TOOL> (standalone) or LOCAL*<TOOLKIT>\_<TOOL>
+             * (extending). Max 60 chars total.
+             */
+            slug: string;
+            /**
+             * If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's
+             * auth/connection status. If omitted, the tool is standalone (no-auth).
+             */
+            extends_toolkit?: string;
+            /**
+             * JSON Schema describing tool output (optional)
+             */
+            output_schema?: {
+                [key: string]: unknown;
+            };
+        }
+    }
+}
+export interface SessionExecuteMetaParams {
     /**
-     * Toolkit configuration - specify either enable toolkits (allowlist) or disable
-     * toolkits (denylist). Mutually exclusive.
+     * The unique slug identifier of the meta tool to execute
      */
-    toolkits?: SessionCreateParams.Enable | SessionCreateParams.Disable;
+    slug: 'COMPOSIO_SEARCH_TOOLS' | 'COMPOSIO_MULTI_EXECUTE_TOOL' | 'COMPOSIO_MANAGE_CONNECTIONS' | 'COMPOSIO_WAIT_FOR_CONNECTIONS' | 'COMPOSIO_REMOTE_WORKBENCH' | 'COMPOSIO_REMOTE_BASH_TOOL' | 'COMPOSIO_GET_TOOL_SCHEMAS' | 'COMPOSIO_UPSERT_RECIPE' | 'COMPOSIO_GET_RECIPE';
     /**
-     * Tool-level configuration per toolkit. Allows you to enable, disable, or filter
-     * by tags for specific tools within each toolkit. Every slug passed in `enable` /
-     * `disable` must be a valid Composio tool slug for that toolkit — invalid or
-     * typo'd slugs fail session creation with a clear error listing which ones didn't
-     * match.
+     * The arguments required by the meta tool
      */
-    tools?: {
-        [key: string]: SessionCreateParams.Enable | SessionCreateParams.Disable | SessionCreateParams.Tags;
+    arguments?: {
+        [key: string]: unknown;
     };
     /**
-     * Configuration for workbench behavior
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
      */
-    workbench?: SessionCreateParams.Workbench;
+    experimental?: SessionExecuteMetaParams.Experimental;
 }
-export declare namespace SessionCreateParams {
+export declare namespace SessionExecuteMetaParams {
     /**
-     * Experimental features - not stable, may be modified or removed in future
-     * versions.
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
      */
     interface Experimental {
-        /**
-         * Customize assistive prompt generation (e.g., timezone).
-         */
-        assistive_prompt_config?: Experimental.AssistivePromptConfig;
         /**
          * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
          * existing Composio toolkits. All tools are no-auth.
@@ -1441,26 +2896,11 @@ export declare namespace SessionCreateParams {
         custom_toolkits?: Array<Experimental.CustomToolkit>;
         /**
          * Custom tools to include in search. Standalone tools need no auth. Tools with
-         * extends_toolkit inherit the Composio toolkit's connection.
-         */
-        custom_tools?: Array<Experimental.CustomTool>;
-        /**
-         * Per-tool elicitation permission config. Default behavior + per-tool
-         * always_allow/always_deny overrides. Mutation via PATCH.
+         * extends_toolkit inherit the Composio toolkit's connection.
          */
-        permissions?: Experimental.Permissions;
+        custom_tools?: Array<Experimental.CustomTool>;
     }
     namespace Experimental {
-        /**
-         * Customize assistive prompt generation (e.g., timezone).
-         */
-        interface AssistivePromptConfig {
-            /**
-             * IANA timezone identifier (e.g., 'America/New_York', 'Europe/London'). Used to
-             * customize the system prompt with timezone-aware instructions.
-             */
-            user_timezone?: string;
-        }
         interface CustomToolkit {
             /**
              * Used for BM25 search matching and shown in toolkit connection statuses.
@@ -1541,9 +2981,89 @@ export declare namespace SessionCreateParams {
                 [key: string]: unknown;
             };
         }
+    }
+}
+export interface SessionLinkParams {
+    /**
+     * The unique slug identifier of the toolkit to connect
+     */
+    toolkit: string;
+    /**
+     * A human-readable alias for this connected account. Must be unique per entity and
+     * toolkit within the project.
+     */
+    alias?: string;
+    /**
+     * URL where users will be redirected after completing auth
+     */
+    callback_url?: string;
+}
+export interface SessionPatchParams {
+    /**
+     * The auth configs to use for the session. This will override the default behavior
+     * and use the given auth config when specific toolkits are being executed
+     */
+    auth_configs?: {
+        [key: string]: string;
+    };
+    /**
+     * The connected accounts to use for the session. This will override the default
+     * behaviour and use the given connected account when specific toolkits are being
+     * executed. Each connected account must exist (not deleted or disabled) and belong
+     * to the same `user_id` as the session — otherwise session creation fails with a
+     * clear error explaining which account didn't match.
+     */
+    connected_accounts?: {
+        [key: string]: string;
+    };
+    execute?: SessionPatchParams.Execute;
+    experimental?: SessionPatchParams.Experimental | null;
+    manage_connections?: SessionPatchParams.ManageConnections | null;
+    multi_account?: SessionPatchParams.MultiAccount | null;
+    /**
+     * Preload configuration. Use an explicit list for frequently used tool slugs, or
+     * "all" to dynamically expose every app tool allowed by positive
+     * toolkits/tools/tags filters.
+     */
+    preload?: SessionPatchParams.Preload;
+    search?: SessionPatchParams.Search;
+    /**
+     * Global MCP tool annotation hints for filtering. Array format is treated as
+     * enabled list. Object format supports both enabled (tool must have at least one)
+     * and disabled (tool must NOT have any) lists. Toolkit-level tags override this.
+     * Toolkit enabled/disabled lists take precedence over tag filtering.
+     */
+    tags?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'> | SessionPatchParams.UnionMember1;
+    /**
+     * Toolkit configuration - specify either enable toolkits (allowlist) or disable
+     * toolkits (denylist). Mutually exclusive.
+     */
+    toolkits?: SessionPatchParams.Enable | SessionPatchParams.Disable;
+    /**
+     * Tool-level configuration per toolkit. Allows you to enable, disable, or filter
+     * by tags for specific tools within each toolkit. Every slug passed in `enable` /
+     * `disable` must be a valid Composio tool slug for that toolkit — invalid or
+     * typo'd slugs fail session creation with a clear error listing which ones didn't
+     * match.
+     */
+    tools?: {
+        [key: string]: SessionPatchParams.Enable | SessionPatchParams.Disable | SessionPatchParams.Tags;
+    };
+    workbench?: SessionPatchParams.Workbench | null;
+}
+export declare namespace SessionPatchParams {
+    interface Execute {
+        enable_multi_execute?: boolean;
+    }
+    interface Experimental {
         /**
-         * Per-tool elicitation permission config. Default behavior + per-tool
-         * always_allow/always_deny overrides. Mutation via PATCH.
+         * Per-tool elicitation permission config. Replaces the stored block when provided.
+         */
+        permissions?: Experimental.Permissions;
+    }
+    namespace Experimental {
+        /**
+         * Per-tool elicitation permission config. Replaces the stored block when provided.
          */
         interface Permissions {
             /**
@@ -1554,18 +3074,19 @@ export declare namespace SessionCreateParams {
              */
             default: 'allow_all' | 'ask_every_call' | 'ask_once_per_session';
             /**
-             * Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? "__none__"}`.
-             * `always_allow` skips the prompt and runs the tool; `always_deny` blocks the
-             * tool. Overrides take precedence over `default` and the session cache.
+             * Per-tool overrides keyed by `${toolSlug}:${connectedAccountId ?? "__none__"}`,
+             * plus account-wide overrides keyed by `*:${connectedAccountId ?? "__none__"}`.
+             * Exact tool overrides take precedence over account-wide overrides. `always_allow`
+             * skips the prompt and runs the tool; `always_deny` blocks the tool; `ask_once`
+             * prompts once per session (allow/deny) and remembers; `ask_always` prompts on
+             * every call with allow-once/allow-session/deny, ignoring any cached session
+             * allow. Overrides take precedence over `default`.
              */
             overrides?: {
-                [key: string]: 'always_allow' | 'always_deny';
+                [key: string]: 'always_allow' | 'always_deny' | 'ask_once' | 'ask_always';
             };
         }
     }
-    /**
-     * Configuration for connection management settings
-     */
     interface ManageConnections {
         /**
          * The URL to redirect to after a user completes authentication for a connected
@@ -1591,10 +3112,6 @@ export declare namespace SessionCreateParams {
          */
         enable_wait_for_connections?: boolean | null;
     }
-    /**
-     * Configure multi-account behavior. When enabled, users can connect multiple
-     * accounts per toolkit.
-     */
     interface MultiAccount {
         /**
          * When true, enables multi-account mode for this session. When not set, falls back
@@ -1613,23 +3130,20 @@ export declare namespace SessionCreateParams {
         require_explicit_selection?: boolean;
     }
     /**
-     * Preload configuration. Controls which tools appear in `session.tools` and the
-     * MCP server tool list so the agent can call them directly without going through
-     * search first — useful for frequently used tools. Each slug must be allowed by
-     * the session filters (`toolkits`, `tools`, `tags`), otherwise session creation
-     * fails with a 400. Custom tools declared in `custom_tools` / `custom_toolkits`
-     * can also be preloaded. Not supported when multi-account is enabled. Each
-     * preloaded tool adds to the agent context window, so keep the list at or under
-     * ~20 tools.
+     * Preload configuration. Use an explicit list for frequently used tool slugs, or
+     * "all" to dynamically expose every app tool allowed by positive
+     * toolkits/tools/tags filters.
      */
     interface Preload {
         /**
-         * Tool slugs to preload. Each slug must be allowed by the session filters
-         * (`toolkits`, `tools`, `tags`) and exist either in the Composio tool catalog or
-         * in `custom_tools` / `custom_toolkits` — unknown or blocked slugs return a 400 at
-         * session creation.
+         * Explicit tool slugs to preload, or "all" to dynamically expose all current and
+         * future app tools allowed by the positive session filters. "all" is capped at
+         * 1000 tools and is not supported without a positive allowlist.
          */
-        tools?: Array<string>;
+        tools?: Array<string> | string;
+    }
+    interface Search {
+        enable?: boolean;
     }
     interface UnionMember1 {
         disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
@@ -1678,9 +3192,6 @@ export declare namespace SessionCreateParams {
             enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
         }
     }
-    /**
-     * Configuration for workbench behavior
-     */
     interface Workbench {
         /**
          * Character threshold for automatic offloading. When workbench response exceeds
@@ -1700,68 +3211,12 @@ export declare namespace SessionCreateParams {
         enable_proxy_execution?: boolean;
         /**
          * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
-         * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+         * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Patching this value recreates the sandbox
+         * on next access — sandbox FS state is lost, but /mnt/files/ R2 mount persists.
          */
         sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
     }
 }
-export interface SessionExecuteParams {
-    /**
-     * The unique slug identifier of the tool to execute. Supports both meta tools and
-     * app tools exposed by the session.
-     */
-    tool_slug: string;
-    /**
-     * Account identifier to specify which connected account to use for direct tool
-     * execution. Use the account ID (e.g. "coup_hurricane_dal_analytical") or an
-     * alias. When omitted with a single account, the default is used. When omitted
-     * with multiple accounts, an error lists available accounts. Meta/helper tools
-     * either ignore this top-level field or define their own account-selection fields,
-     * for example COMPOSIO_MULTI_EXECUTE_TOOL.tools[].account.
-     */
-    account?: string;
-    /**
-     * The arguments required by the tool
-     */
-    arguments?: {
-        [key: string]: unknown;
-    };
-    /**
-     * When true, direct non-meta tool execution may return a workbench offload preview
-     * if the response exceeds the configured threshold and the session workbench is
-     * enabled. When omitted or false, direct tool execution returns the normal inline
-     * response. Meta/helper tools are unaffected, and COMPOSIO_MULTI_EXECUTE_TOOL uses
-     * session.workbench configuration for its own batch-level offload behavior.
-     */
-    enable_auto_workbench_offload?: boolean;
-}
-export interface SessionExecuteMetaParams {
-    /**
-     * The unique slug identifier of the meta tool to execute
-     */
-    slug: 'COMPOSIO_SEARCH_TOOLS' | 'COMPOSIO_MULTI_EXECUTE_TOOL' | 'COMPOSIO_MANAGE_CONNECTIONS' | 'COMPOSIO_WAIT_FOR_CONNECTIONS' | 'COMPOSIO_REMOTE_WORKBENCH' | 'COMPOSIO_REMOTE_BASH_TOOL' | 'COMPOSIO_GET_TOOL_SCHEMAS' | 'COMPOSIO_UPSERT_RECIPE' | 'COMPOSIO_GET_RECIPE';
-    /**
-     * The arguments required by the meta tool
-     */
-    arguments?: {
-        [key: string]: unknown;
-    };
-}
-export interface SessionLinkParams {
-    /**
-     * The unique slug identifier of the toolkit to connect
-     */
-    toolkit: string;
-    /**
-     * A human-readable alias for this connected account. Must be unique per entity and
-     * toolkit within the project.
-     */
-    alias?: string;
-    /**
-     * URL where users will be redirected after completing auth
-     */
-    callback_url?: string;
-}
 export interface SessionProxyExecuteParams {
     /**
      * The API endpoint to call (absolute URL or path relative to base URL of the
@@ -2260,12 +3715,16 @@ export declare namespace SessionProxyExecuteParams {
 }
 export interface SessionSearchParams {
     /**
-     * List of search queries to execute in parallel. Up to 7 queries supported.
+     * List of search queries to execute in parallel.
      */
     queries: Array<SessionSearchParams.Query>;
     /**
-     * Optional model hint for search/planning behavior (e.g., "gpt-4o"). Ignored if
-     * invalid.
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
+     */
+    experimental?: SessionSearchParams.Experimental;
+    /**
+     * Optional model hint for search/planning behavior (e.g., "gpt-4o").
      */
     model?: string;
 }
@@ -2282,6 +3741,104 @@ export declare namespace SessionSearchParams {
          */
         known_fields?: string;
     }
+    /**
+     * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+     * customs — pass them on every request that needs them.
+     */
+    interface Experimental {
+        /**
+         * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+         * existing Composio toolkits. All tools are no-auth.
+         */
+        custom_toolkits?: Array<Experimental.CustomToolkit>;
+        /**
+         * Custom tools to include in search. Standalone tools need no auth. Tools with
+         * extends_toolkit inherit the Composio toolkit's connection.
+         */
+        custom_tools?: Array<Experimental.CustomTool>;
+    }
+    namespace Experimental {
+        interface CustomToolkit {
+            /**
+             * Used for BM25 search matching and shown in toolkit connection statuses.
+             */
+            description: string;
+            /**
+             * Display name shown to the LLM and in search results.
+             */
+            name: string;
+            /**
+             * Unique slug for the toolkit. Must not conflict with existing Composio toolkit
+             * slugs. Alphanumeric, underscores, and hyphens only.
+             */
+            slug: string;
+            /**
+             * Tools in this custom toolkit
+             */
+            tools: Array<CustomToolkit.Tool>;
+        }
+        namespace CustomToolkit {
+            interface Tool {
+                /**
+                 * Used for BM25 search matching and shown to the LLM.
+                 */
+                description: string;
+                /**
+                 * Must have type: "object" and a properties field.
+                 */
+                input_schema: {
+                    [key: string]: unknown;
+                };
+                /**
+                 * Human-readable display name
+                 */
+                name: string;
+                /**
+                 * Tool slug. Combined with toolkit slug to form LOCAL*<TOOLKIT>*<TOOL> (max 60
+                 * chars total).
+                 */
+                slug: string;
+                /**
+                 * Optional output schema for the tool response.
+                 */
+                output_schema?: {
+                    [key: string]: unknown;
+                };
+            }
+        }
+        interface CustomTool {
+            /**
+             * Used for BM25 search matching and shown to the LLM.
+             */
+            description: string;
+            /**
+             * Must have type: "object" and a properties field.
+             */
+            input_schema: {
+                [key: string]: unknown;
+            };
+            /**
+             * Human-readable display name
+             */
+            name: string;
+            /**
+             * Tool slug. Forms LOCAL*<TOOL> (standalone) or LOCAL*<TOOLKIT>\_<TOOL>
+             * (extending). Max 60 chars total.
+             */
+            slug: string;
+            /**
+             * If set, must be a valid Composio toolkit slug. The tool inherits that toolkit's
+             * auth/connection status. If omitted, the tool is standalone (no-auth).
+             */
+            extends_toolkit?: string;
+            /**
+             * JSON Schema describing tool output (optional)
+             */
+            output_schema?: {
+                [key: string]: unknown;
+            };
+        }
+    }
 }
 export interface SessionToolkitsParams {
     /**
@@ -2311,9 +3868,20 @@ export interface SessionToolkitsParams {
     toolkits?: Array<string> | null;
 }
 export interface SessionToolsParams {
+    /**
+     * Cursor for pagination. The cursor is a base64 encoded string of the page and
+     * limit. The page is the page number and the limit is the number of items per
+     * page. The cursor is used to paginate through the items. The cursor is not
+     * required for the first page.
+     */
+    cursor?: string;
+    /**
+     * Number of items per page, max allowed is 500
+     */
+    limit?: number;
 }
 export declare namespace Session {
-    export { type SessionCreateResponse as SessionCreateResponse, type SessionRetrieveResponse as SessionRetrieveResponse, type SessionExecuteResponse as SessionExecuteResponse, type SessionExecuteMetaResponse as SessionExecuteMetaResponse, type SessionLinkResponse as SessionLinkResponse, type SessionProxyExecuteResponse as SessionProxyExecuteResponse, type SessionSearchResponse as SessionSearchResponse, type SessionToolkitsResponse as SessionToolkitsResponse, type SessionToolsResponse as SessionToolsResponse, type SessionCreateParams as SessionCreateParams, type SessionExecuteParams as SessionExecuteParams, type SessionExecuteMetaParams as SessionExecuteMetaParams, type SessionLinkParams as SessionLinkParams, type SessionProxyExecuteParams as SessionProxyExecuteParams, type SessionSearchParams as SessionSearchParams, type SessionToolkitsParams as SessionToolkitsParams, type SessionToolsParams as SessionToolsParams, };
+    export { type SessionCreateResponse as SessionCreateResponse, type SessionRetrieveResponse as SessionRetrieveResponse, type SessionAttachResponse as SessionAttachResponse, type SessionConfigHistoryResponse as SessionConfigHistoryResponse, type SessionExecuteResponse as SessionExecuteResponse, type SessionExecuteMetaResponse as SessionExecuteMetaResponse, type SessionLinkResponse as SessionLinkResponse, type SessionPatchResponse as SessionPatchResponse, type SessionProxyExecuteResponse as SessionProxyExecuteResponse, type SessionSearchResponse as SessionSearchResponse, type SessionToolkitsResponse as SessionToolkitsResponse, type SessionToolsResponse as SessionToolsResponse, type SessionCreateParams as SessionCreateParams, type SessionAttachParams as SessionAttachParams, type SessionConfigHistoryParams as SessionConfigHistoryParams, type SessionExecuteParams as SessionExecuteParams, type SessionExecuteMetaParams as SessionExecuteMetaParams, type SessionLinkParams as SessionLinkParams, type SessionPatchParams as SessionPatchParams, type SessionProxyExecuteParams as SessionProxyExecuteParams, type SessionSearchParams as SessionSearchParams, type SessionToolkitsParams as SessionToolkitsParams, type SessionToolsParams as SessionToolsParams, };
     export { Files as Files, type FileListResponse as FileListResponse, type FileDeleteResponse as FileDeleteResponse, type FileCreateDownloadURLResponse as FileCreateDownloadURLResponse, type FileCreateUploadURLResponse as FileCreateUploadURLResponse, type FileListParams as FileListParams, type FileDeleteParams as FileDeleteParams, type FileCreateDownloadURLParams as FileCreateDownloadURLParams, type FileCreateUploadURLParams as FileCreateUploadURLParams, };
 }
 //# sourceMappingURL=session.d.mts.map