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

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

@@ -37,7 +37,7 @@ export class Session extends APIResource {
    * ```
    */
   create(body: SessionCreateParams, options?: RequestOptions): APIPromise<SessionCreateResponse> {
-    return this._client.post('/api/v3/tool_router/session', { body, ...options });
+    return this._client.post('/api/v3.1/tool_router/session', { body, ...options });
   }
 
   /**
@@ -52,20 +52,53 @@ export class Session extends APIResource {
    * ```
    */
   retrieve(sessionID: string, options?: RequestOptions): APIPromise<SessionRetrieveResponse> {
-    return this._client.get(path`/api/v3/tool_router/session/${sessionID}`, options);
+    return this._client.get(path`/api/v3.1/tool_router/session/${sessionID}`, options);
   }
 
   /**
-   * 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> {
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/attach`, { body, ...options });
+  }
+
+  /**
+   * 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> {
+    return this._client.get(path`/api/v3.1/tool_router/session/${sessionID}/config_history`, {
+      query,
+      ...options,
+    });
+  }
+
+  /**
+   * Execute a tool (meta or app) within an existing tool router session.
    *
    * @example
    * ```ts
@@ -80,13 +113,12 @@ export class Session extends APIResource {
     body: SessionExecuteParams,
     options?: RequestOptions,
   ): APIPromise<SessionExecuteResponse> {
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute`, { body, ...options });
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/execute`, { body, ...options });
   }
 
   /**
-   * 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
@@ -102,7 +134,7 @@ export class Session extends APIResource {
     body: SessionExecuteMetaParams,
     options?: RequestOptions,
   ): APIPromise<SessionExecuteMetaResponse> {
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute_meta`, {
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/execute_meta`, {
       body,
       ...options,
     });
@@ -126,7 +158,28 @@ export class Session extends APIResource {
     body: SessionLinkParams,
     options?: RequestOptions,
   ): APIPromise<SessionLinkResponse> {
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/link`, { body, ...options });
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/link`, { body, ...options });
+  }
+
+  /**
+   * 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> {
+    return this._client.patch(path`/api/v3.1/tool_router/session/${sessionID}`, { body, ...options });
   }
 
   /**
@@ -156,16 +209,15 @@ export class Session extends APIResource {
     body: SessionProxyExecuteParams,
     options?: RequestOptions,
   ): APIPromise<SessionProxyExecuteResponse> {
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/proxy_execute`, {
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/proxy_execute`, {
       body,
       ...options,
     });
   }
 
   /**
-   * 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
@@ -184,7 +236,7 @@ export class Session extends APIResource {
     body: SessionSearchParams,
     options?: RequestOptions,
   ): APIPromise<SessionSearchResponse> {
-    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/search`, { body, ...options });
+    return this._client.post(path`/api/v3.1/tool_router/session/${sessionID}/search`, { body, ...options });
   }
 
   /**
@@ -204,13 +256,12 @@ export class Session extends APIResource {
     query: SessionToolkitsParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<SessionToolkitsResponse> {
-    return this._client.get(path`/api/v3/tool_router/session/${sessionID}/toolkits`, { query, ...options });
+    return this._client.get(path`/api/v3.1/tool_router/session/${sessionID}/toolkits`, { query, ...options });
   }
 
   /**
-   * 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
@@ -221,16 +272,16 @@ export class Session extends APIResource {
    */
   tools(
     sessionID: string,
-    query?: SessionToolsParams | null | undefined,
+    query: SessionToolsParams | null | undefined = {},
     options?: RequestOptions,
   ): APIPromise<SessionToolsResponse> {
-    return this._client.get(path`/api/v3/tool_router/session/${sessionID}/tools`, options);
+    return this._client.get(path`/api/v3.1/tool_router/session/${sessionID}/tools`, { query, ...options });
   }
 }
 
 export interface SessionCreateResponse {
   /**
-   * The session configuration including user, toolkits, and overrides
+   * The configuration used to create this session
    */
   config: SessionCreateResponse.Config;
 
@@ -267,18 +318,25 @@ export interface SessionCreateResponse {
 
 export namespace SessionCreateResponse {
   /**
-   * The session configuration including user, toolkits, and overrides
+   * The configuration used to create this session
    */
   export 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
      */
@@ -330,19 +388,29 @@ export namespace SessionCreateResponse {
 
   export 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
+     */
+    export interface Execute {
+      enable_multi_execute?: boolean;
+    }
+
+    /**
+     * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+     * is returned as "all".
      */
     export 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
+     */
+    export interface Search {
+      enable?: boolean;
     }
 
     /**
@@ -579,7 +647,7 @@ export namespace SessionCreateResponse {
 
 export interface SessionRetrieveResponse {
   /**
-   * The session configuration including user, toolkits, and overrides
+   * The configuration used to create this session
    */
   config: SessionRetrieveResponse.Config;
 
@@ -615,18 +683,25 @@ export interface SessionRetrieveResponse {
 
 export namespace SessionRetrieveResponse {
   /**
-   * The session configuration including user, toolkits, and overrides
+   * The configuration used to create this session
    */
   export 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
      */
@@ -678,19 +753,29 @@ export namespace SessionRetrieveResponse {
 
   export 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
+     */
+    export interface Execute {
+      enable_multi_execute?: boolean;
+    }
+
+    /**
+     * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+     * is returned as "all".
      */
     export 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
+     */
+    export interface Search {
+      enable?: boolean;
     }
 
     /**
@@ -924,436 +1009,374 @@ export namespace SessionRetrieveResponse {
   }
 }
 
-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 {
+export interface SessionAttachResponse {
   /**
-   * The unique identifier for the connected account
+   * The configuration used to create this session
    */
-  connected_account_id: string;
+  config: SessionAttachResponse.Config;
 
   /**
-   * Token used to complete the authentication flow
+   * Monotonic version of the config. Incremented on each PATCH. Use for optimistic
+   * concurrency control.
    */
-  link_token: string;
+  config_version: number;
 
-  /**
-   * The URL where users should be redirected to complete OAuth
-   */
-  redirect_url: string;
-}
+  mcp: SessionAttachResponse.Mcp;
 
-export interface SessionProxyExecuteResponse {
   /**
-   * 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 namespace SessionProxyExecuteResponse {
+export namespace SessionAttachResponse {
   /**
-   * Binary body response data. Present when the response is a binary file.
+   * The configuration used to create this session
    */
-  export interface BinaryData {
+  export interface Config {
     /**
-     * Content-Type of the binary data
+     * Execute helper configuration
      */
-    content_type: string;
+    execute: Config.Execute;
 
     /**
-     * File size in bytes
+     * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+     * is returned as "all".
      */
-    size: number;
+    preload: Config.Preload;
 
     /**
-     * URL to download binary content
+     * Search helper configuration
      */
-    url: string;
+    search: Config.Search;
 
     /**
-     * ISO 8601 timestamp when the URL expires
+     * User identifier for this session
      */
-    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>;
-}
+    user_id: string;
 
-export namespace SessionSearchResponse {
-  export interface Result {
     /**
-     * 1-based index of the query in the request
+     * Auth config overrides per toolkit
      */
-    index: number;
+    auth_configs?: { [key: string]: string };
 
     /**
-     * List of main tool slugs matching the search criteria
+     * Connected account overrides per toolkit. Each connected account must belong to
+     * the same user_id as the session.
      */
-    primary_tool_slugs: Array<string>;
+    connected_accounts?: { [key: string]: string };
 
     /**
-     * List of related tool slugs that might be useful
+     * Manage connections configuration
      */
-    related_tool_slugs: Array<string>;
+    manage_connections?: Config.ManageConnections;
 
     /**
-     * List of unique toolkit slugs used by tools in this query
+     * Multi-account configuration for this session.
      */
-    toolkits: Array<string>;
+    multi_account?: Config.MultiAccount;
 
     /**
-     * The use case that was searched
+     * 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.
      */
-    use_case: string;
+    tags?: Config.Tags;
 
     /**
-     * Task difficulty assessment (e.g., "easy - Simple single-tool operation with
-     * known parameters")
+     * Toolkit configuration - either enabled list or disabled list
      */
-    difficulty?: string;
+    toolkits?: Config.Enabled | Config.Disabled;
 
     /**
-     * Error message if the search for this query failed, null otherwise. Always
-     * present for failed queries.
+     * Tool-level configuration per toolkit
      */
-    error?: string | null;
+    tools?: { [key: string]: Config.Enabled | Config.Disabled | Config.Tags };
 
     /**
-     * Guidance message about the search results, particularly when a cached plan is
-     * available
+     * Workbench configuration
      */
-    execution_guidance?: string;
+    workbench?: Config.Workbench;
+  }
 
+  export namespace Config {
     /**
-     * Common pitfalls and considerations (only present when cached plan is available)
+     * Execute helper configuration
      */
-    known_pitfalls?: Array<string>;
+    export interface Execute {
+      enable_multi_execute?: boolean;
+    }
 
     /**
-     * Memory data relevant to this query, grouped by app. Only present for non-cached
-     * search results.
+     * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+     * is returned as "all".
      */
-    memory?: { [key: string]: Array<string> };
+    export interface Preload {
+      /**
+       * Explicit preloaded tool slugs, or "all" when the session dynamically exposes all
+       * app tools allowed by its filters.
+       */
+      tools: Array<string> | 'all';
+    }
 
     /**
-     * ID of cached plan if available
+     * Search helper configuration
      */
-    plan_id?: string;
+    export interface Search {
+      enable?: boolean;
+    }
 
     /**
-     * Workflow steps from cached plan (only present when cached plan is available)
+     * Manage connections configuration
      */
-    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>;
-  }
+    export interface ManageConnections {
+      /**
+       * Custom callback URL for connected account auth flows
+       */
+      callback_url?: string;
 
-  export namespace Result {
-    export interface ReferenceWorkbenchSnippet {
       /**
-       * Python code snippet for the workbench
+       * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS. Default true.
        */
-      code: string;
+      enable_connection_removal?: boolean;
 
       /**
-       * Description of what the code snippet does
+       * Enable the COMPOSIO_WAIT_FOR_CONNECTIONS tool for polling connection status.
+       * Default false. May not work reliably with GPT models.
        */
-      description: string;
-    }
-  }
+      enable_wait_for_connections?: boolean;
 
-  /**
-   * Session info for correlating meta tool calls
-   */
-  export interface Session {
-    /**
-     * Session identifier to be passed to subsequent meta tool calls as session_id.
-     */
-    id: string;
+      /**
+       * Whether to enable the connection manager for automatic connection handling
+       */
+      enabled?: boolean;
+    }
 
     /**
-     * Whether a fresh session id was generated in this call.
+     * Multi-account configuration for this session.
      */
-    generate_id: boolean;
+    export interface MultiAccount {
+      /**
+       * When true, enables multi-account mode for this session. When not set, falls back
+       * to org/project-level configuration.
+       */
+      enable?: boolean;
 
-    /**
-     * LLM-facing guidance on how to reuse this session id
-     */
-    instructions: string;
-  }
+      /**
+       * Maximum number of connected accounts allowed per toolkit. Defaults to 5 when
+       * multi-account is enabled.
+       */
+      max_accounts_per_toolkit?: number;
 
-  /**
-   * Time information for the query
-   */
-  export interface TimeInfo {
-    /**
-     * Current time in ISO format (UTC)
-     */
-    current_time_utc: string;
+      /**
+       * When true, require explicit account selection when multiple accounts are
+       * connected. When false (default), use the first/default account.
+       */
+      require_explicit_selection?: boolean;
+    }
 
     /**
-     * Current time as Unix epoch timestamp in seconds
+     * 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.
      */
-    current_time_utc_epoch_seconds: number;
+    export interface Tags {
+      /**
+       * Tags that the tool must NOT have any of
+       */
+      disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
 
-    /**
-     * Important message about time handling and timezone considerations
-     */
-    message: string;
-  }
+      /**
+       * Tags that the tool must have at least one of
+       */
+      enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+    }
 
-  export interface ToolSchemas {
-    /**
-     * The slug of the tool
-     */
-    tool_slug: string;
+    export interface Enabled {
+      enabled: Array<string>;
+    }
 
-    /**
-     * The slug of the toolkit that provides this tool
-     */
-    toolkit: string;
+    export interface Disabled {
+      disabled: Array<string>;
+    }
 
-    /**
-     * Description of the tool
-     */
-    description?: string;
+    export interface Enabled {
+      enabled: Array<string>;
+    }
 
-    /**
-     * Whether the full input_schema is included in this response
-     */
-    hasFullSchema?: boolean;
+    export interface Disabled {
+      disabled: Array<string>;
+    }
 
-    /**
-     * Input schema for the tool (only present when hasFullSchema is true)
-     */
-    input_schema?: { [key: string]: unknown };
+    export interface Tags {
+      tags: Tags.Tags;
+    }
 
-    /**
-     * Output/response schema for the tool. Only included when include_output_schemas
-     * is true.
-     */
-    output_schema?: { [key: string]: unknown };
+    export namespace Tags {
+      export interface Tags {
+        /**
+         * Tags that the tool must NOT have any of
+         */
+        disabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
 
-    /**
-     * Reference to fetch full schema when hasFullSchema is false
-     */
-    schemaRef?: ToolSchemas.SchemaRef;
-  }
+        /**
+         * Tags that the tool must have at least one of
+         */
+        enabled?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+      }
+    }
 
-  export namespace ToolSchemas {
     /**
-     * Reference to fetch full schema when hasFullSchema is false
+     * Workbench configuration
      */
-    export interface SchemaRef {
+    export interface Workbench {
       /**
-       * Arguments to pass to the tool
+       * Character threshold after which tool execution response are saved to a file in
+       * workbench. Default is 20k.
        */
-      args: SchemaRef.Args;
+      auto_offload_threshold?: number;
 
       /**
-       * Tool to call
+       * Whether the workbench (code execution sandbox) is enabled. When false,
+       * COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL are not exposed.
        */
-      tool: 'COMPOSIO_GET_TOOL_SCHEMAS';
+      enable?: boolean;
 
       /**
-       * Instruction message for the LLM
+       * Whether proxy execution is enabled in the workbench
        */
-      message?: string;
-    }
+      proxy_execution_enabled?: boolean;
 
-    export namespace SchemaRef {
       /**
-       * Arguments to pass to the tool
+       * 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.
        */
-      export interface Args {
-        /**
-         * Tool slugs to fetch schemas for
-         */
-        tool_slugs: Array<string>;
-      }
+      sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
     }
   }
 
-  export interface ToolkitConnectionStatus {
+  export interface Mcp {
     /**
-     * Description of what the toolkit does and its capabilities
+     * The type of the MCP server. Can be http
      */
-    description: string;
+    type: 'http';
 
     /**
-     * Whether an active connection exists for this toolkit
+     * The URL of the MCP server
      */
-    has_active_connection: boolean;
+    url: string;
+  }
 
+  /**
+   * Experimental features
+   */
+  export interface Experimental {
     /**
-     * Human-readable message about the connection status and next steps
+     * The assistive system prompt for the tool router session
      */
-    status_message: string;
+    assistive_prompt?: string;
 
     /**
-     * The toolkit slug identifier (e.g., "gmail", "slack")
+     * User-defined custom toolkits with grouped tools (no-auth)
      */
-    toolkit: string;
+    custom_toolkits?: Array<Experimental.CustomToolkit>;
 
     /**
-     * When "required", the agent must specify which account to use. Present only when
-     * multiple accounts exist.
+     * Custom tools — standalone or extending Composio toolkits
      */
-    account_selection?: 'required';
+    custom_tools?: Array<Experimental.CustomTool>;
+  }
 
-    /**
-     * List of connected accounts for this toolkit. Present when multi-account is
-     * enabled.
-     */
-    accounts?: Array<ToolkitConnectionStatus.Account>;
+  export namespace Experimental {
+    export interface CustomToolkit {
+      description: string;
 
-    /**
-     * Connection details including auth config and connected account IDs. Only present
-     * when has_active_connection is true.
-     */
-    connection_details?: { [key: string]: unknown };
+      name: string;
 
-    /**
-     * Information about the currently connected user (email, name, etc.)
-     */
-    current_user_info?: { [key: string]: unknown };
-  }
+      slug: string;
 
-  export namespace ToolkitConnectionStatus {
-    export interface Account {
-      /**
-       * Unique identifier for this account
-       */
-      id: string;
+      tools: Array<CustomToolkit.Tool>;
+    }
 
-      /**
-       * ISO 8601 timestamp of when the account was connected
-       */
-      created_at: string;
+    export namespace CustomToolkit {
+      export interface Tool {
+        description: string;
 
-      /**
-       * Whether this is the default account for the toolkit
-       */
-      is_default: boolean;
+        input_schema: { [key: string]: unknown };
 
-      /**
-       * Connection status (e.g., "active")
-       */
-      status: string;
+        name: string;
 
-      /**
-       * User-assigned alias for this account
-       */
-      alias?: 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 };
+      }
+    }
+
+    export interface CustomTool {
+      description: string;
+
+      input_schema: { [key: string]: unknown };
+
+      name: string;
 
       /**
-       * Information about the connected user (email, name, etc.)
+       * Original tool slug as provided by the user
        */
-      user_info?: { [key: string]: unknown };
+      original_slug: string;
+
+      /**
+       * Prefixed tool slug (e.g. LOCAL_GMAIL_GET_IMPORTANT_EMAILS)
+       */
+      slug: string;
+
+      extends_toolkit?: string;
+
+      output_schema?: { [key: string]: unknown };
     }
   }
+
+  export 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 SessionToolkitsResponse {
+export interface SessionConfigHistoryResponse {
   current_page: number;
 
-  items: Array<SessionToolkitsResponse.Item>;
+  items: Array<SessionConfigHistoryResponse.Item>;
 
   total_items: number;
 
@@ -1362,356 +1385,2036 @@ export interface SessionToolkitsResponse {
   next_cursor?: string | null;
 }
 
-export namespace SessionToolkitsResponse {
+export namespace SessionConfigHistoryResponse {
   export interface Item {
     /**
-     * Available Composio-managed auth schemes
+     * The session configuration at this version
      */
-    composio_managed_auth_schemes: Array<string>;
+    config: Item.Config;
 
     /**
-     * Connected account if available
+     * ISO timestamp. For history rows, when the entry was archived (i.e. the moment
+     * the version was superseded by a PATCH).
      */
-    connected_account: Item.ConnectedAccount | null;
+    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;
+  }
+
+  export namespace Item {
+    /**
+     * The session configuration at this version
+     */
+    export 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;
+    }
+
+    export namespace Config {
+      /**
+       * Execute helper configuration
+       */
+      export interface Execute {
+        enable_multi_execute?: boolean;
+      }
+
+      /**
+       * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+       * is returned as "all".
+       */
+      export 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
+       */
+      export interface Search {
+        enable?: boolean;
+      }
+
+      /**
+       * Manage connections configuration
+       */
+      export 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.
+       */
+      export 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.
+       */
+      export 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'>;
+      }
+
+      export interface Enabled {
+        enabled: Array<string>;
+      }
+
+      export interface Disabled {
+        disabled: Array<string>;
+      }
+
+      export interface Enabled {
+        enabled: Array<string>;
+      }
+
+      export interface Disabled {
+        disabled: Array<string>;
+      }
+
+      export interface Tags {
+        tags: Tags.Tags;
+      }
+
+      export namespace Tags {
+        export 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
+       */
+      export 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 namespace SessionPatchResponse {
+  /**
+   * The configuration used to create this session
+   */
+  export 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;
+  }
+
+  export namespace Config {
+    /**
+     * Execute helper configuration
+     */
+    export interface Execute {
+      enable_multi_execute?: boolean;
+    }
+
+    /**
+     * Preload configuration. Explicit slugs are returned as an array; dynamic preload
+     * is returned as "all".
+     */
+    export 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
+     */
+    export interface Search {
+      enable?: boolean;
+    }
+
+    /**
+     * Manage connections configuration
+     */
+    export 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.
+     */
+    export 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.
+     */
+    export 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'>;
+    }
+
+    export interface Enabled {
+      enabled: Array<string>;
+    }
+
+    export interface Disabled {
+      disabled: Array<string>;
+    }
+
+    export interface Enabled {
+      enabled: Array<string>;
+    }
+
+    export interface Disabled {
+      disabled: Array<string>;
+    }
+
+    export interface Tags {
+      tags: Tags.Tags;
+    }
+
+    export namespace Tags {
+      export 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
+     */
+    export 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 Mcp {
+    /**
+     * The type of the MCP server. Can be http
+     */
+    type: 'http';
+
+    /**
+     * The URL of the MCP server
+     */
+    url: string;
+  }
+
+  /**
+   * Experimental features
+   */
+  export 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>;
+  }
+
+  export namespace Experimental {
+    export interface CustomToolkit {
+      description: string;
+
+      name: string;
+
+      slug: string;
+
+      tools: Array<CustomToolkit.Tool>;
+    }
+
+    export namespace CustomToolkit {
+      export 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 };
+      }
+    }
+
+    export 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 };
+    }
+  }
+
+  export 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 namespace SessionProxyExecuteResponse {
+  /**
+   * Binary body response data. Present when the response is a binary file.
+   */
+  export 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 namespace SessionSearchResponse {
+  export 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>;
+  }
+
+  export namespace Result {
+    export 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
+   */
+  export 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
+     */
+    instructions: string;
+  }
+
+  /**
+   * Time information for the query
+   */
+  export interface TimeInfo {
+    /**
+     * Current time in ISO format (UTC)
+     */
+    current_time_utc: string;
+
+    /**
+     * Current time as Unix epoch timestamp in seconds
+     */
+    current_time_utc_epoch_seconds: number;
+
+    /**
+     * Important message about time handling and timezone considerations
+     */
+    message: string;
+  }
+
+  export interface ToolSchemas {
+    /**
+     * The slug of the tool
+     */
+    tool_slug: string;
+
+    /**
+     * The slug of the toolkit that provides this tool
+     */
+    toolkit: string;
+
+    /**
+     * Description of the tool
+     */
+    description?: string;
+
+    /**
+     * Whether the full input_schema is included in this response
+     */
+    hasFullSchema?: boolean;
+
+    /**
+     * Input schema for the tool (only present when hasFullSchema is true)
+     */
+    input_schema?: { [key: string]: unknown };
+
+    /**
+     * Output/response schema for the tool. Only included when include_output_schemas
+     * is true.
+     */
+    output_schema?: { [key: string]: unknown };
+
+    /**
+     * Reference to fetch full schema when hasFullSchema is false
+     */
+    schemaRef?: ToolSchemas.SchemaRef;
+  }
+
+  export namespace ToolSchemas {
+    /**
+     * Reference to fetch full schema when hasFullSchema is false
+     */
+    export interface SchemaRef {
+      /**
+       * Arguments to pass to the tool
+       */
+      args: SchemaRef.Args;
+
+      /**
+       * Tool to call
+       */
+      tool: 'COMPOSIO_GET_TOOL_SCHEMAS';
+
+      /**
+       * Instruction message for the LLM
+       */
+      message?: string;
+    }
+
+    export namespace SchemaRef {
+      /**
+       * Arguments to pass to the tool
+       */
+      export interface Args {
+        /**
+         * Tool slugs to fetch schemas for
+         */
+        tool_slugs: Array<string>;
+      }
+    }
+  }
+
+  export interface ToolkitConnectionStatus {
+    /**
+     * Description of what the toolkit does and its capabilities
+     */
+    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 };
+  }
+
+  export namespace ToolkitConnectionStatus {
+    export 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 namespace SessionToolkitsResponse {
+  export 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;
+  }
+
+  export namespace Item {
+    /**
+     * Connected account if available
+     */
+    export 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;
+    }
+
+    export namespace ConnectedAccount {
+      /**
+       * Auth config details
+       */
+      export 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
+     */
+    export 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 namespace SessionToolsResponse {
+  export 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;
+
+    /**
+     * Schema definition of return values from the tool
+     */
+    output_parameters: { [key: string]: unknown };
+
+    /**
+     * Structured scope requirements for the tool. Null means the tool is legacy and
+     * only exposes flat scopes.
+     */
+    scope_requirements: Item.ScopeRequirements | null;
+
+    /**
+     * List of scopes associated with the tool
+     */
+    scopes: Array<string>;
+
+    /**
+     * Unique identifier for the tool
+     */
+    slug: string;
+
+    /**
+     * List of tags associated with the tool for categorization and filtering
+     */
+    tags: Array<string>;
+
+    toolkit: Item.Toolkit;
+
+    /**
+     * Current version of the tool
+     */
+    version: string;
+
+    /**
+     * Human-friendly description of the tool, if available
+     */
+    human_description?: string;
+  }
+
+  export namespace Item {
+    export interface Deprecated {
+      /**
+       * List of all available versions for this tool
+       */
+      available_versions: Array<string>;
+
+      /**
+       * The display name of the tool
+       */
+      displayName: string;
+
+      /**
+       * Indicates if this tool is deprecated and may be removed in the future
+       */
+      is_deprecated: boolean;
+
+      toolkit: Deprecated.Toolkit;
+
+      /**
+       * Current version identifier of the tool
+       */
+      version: string;
+    }
+
+    export namespace Deprecated {
+      export 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.
+     */
+    export interface ScopeRequirements {
+      all_of: Array<string | ScopeRequirements.AnyOf>;
+    }
+
+    export namespace ScopeRequirements {
+      export interface AnyOf {
+        any_of: Array<string>;
+      }
+    }
+
+    export interface Toolkit {
+      /**
+       * URL to the toolkit logo image
+       */
+      logo: string;
+
+      /**
+       * Human-readable name of the parent toolkit
+       */
+      name: string;
+
+      /**
+       * Unique identifier of the parent toolkit
+       */
+      slug: string;
+    }
+  }
+}
+
+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 namespace SessionCreateParams {
+  export interface Execute {
+    enable_multi_execute?: boolean;
+  }
+
+  /**
+   * Experimental features - not stable, may be modified or removed in future
+   * versions.
+   */
+  export 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.
+     */
+    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.
+     */
+    permissions?: Experimental.Permissions;
+  }
+
+  export namespace Experimental {
+    /**
+     * Customize assistive prompt generation (e.g., timezone).
+     */
+    export 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;
+    }
+
+    export 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>;
+    }
+
+    export namespace CustomToolkit {
+      export 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 };
+      }
+    }
+
+    export 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 };
+    }
+
+    /**
+     * Per-tool elicitation permission config. Default behavior + per-tool
+     * always_allow/always_deny overrides. Mutation via PATCH.
+     */
+    export interface Permissions {
+      /**
+       * 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.
+       */
+      default: 'allow_all' | 'ask_every_call' | 'ask_once_per_session';
+
+      /**
+       * 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' | 'ask_once' | 'ask_always' };
+    }
+  }
+
+  /**
+   * Configuration for connection management settings
+   */
+  export interface ManageConnections {
+    /**
+     * The URL to redirect to after a user completes authentication for a connected
+     * account. This allows you to handle the auth callback in your own application.
+     */
+    callback_url?: string;
+
+    /**
+     * 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.
+     */
+    enable?: boolean | null;
+
+    /**
+     * Enable the "remove" action in COMPOSIO_MANAGE_CONNECTIONS to allow deleting
+     * connected accounts. Default true.
+     */
+    enable_connection_removal?: boolean | null;
+
+    /**
+     * 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.
+     */
+    enable_wait_for_connections?: boolean | null;
+  }
+
+  /**
+   * Configure multi-account behavior. When enabled, users can connect multiple
+   * accounts per toolkit.
+   */
+  export 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. Must be between 2
+     * and 10.
+     */
+    max_accounts_per_toolkit?: number;
+
+    /**
+     * When true, the agent must explicitly select which account to use. When false
+     * (default), the first/default account is used automatically.
+     */
+    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.
+   */
+  export interface Preload {
+    /**
+     * 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> | string;
+  }
+
+  export interface Search {
+    enable?: boolean;
+  }
+
+  export interface UnionMember1 {
+    disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+
+    enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+  }
+
+  /**
+   * Enable only specific toolkits (allowlist)
+   */
+  export interface Enable {
+    /**
+     * Only these specific toolkits will be enabled
+     */
+    enable: Array<string>;
+  }
+
+  /**
+   * Disable specific toolkits (denylist)
+   */
+  export interface Disable {
+    /**
+     * These specific toolkits will be disabled
+     */
+    disable: Array<string>;
+  }
+
+  export interface Enable {
+    /**
+     * Only these specific tools will be available for this toolkit
+     */
+    enable: Array<string>;
+  }
+
+  export interface Disable {
+    /**
+     * These specific tools will be disabled for this toolkit
+     */
+    disable: Array<string>;
+  }
+
+  export interface Tags {
+    /**
+     * MCP tags to filter tools. Array format is treated as enabled list. Object format
+     * supports both enabled and disabled lists.
+     */
+    tags: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'> | Tags.UnionMember1;
+  }
+
+  export namespace Tags {
+    export interface UnionMember1 {
+      disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+
+      enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+    }
+  }
 
+  /**
+   * Configuration for workbench behavior
+   */
+  export interface Workbench {
     /**
-     * Whether the toolkit is enabled
+     * 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.
      */
-    enabled: boolean;
+    auto_offload_threshold?: number;
 
     /**
-     * Whether the toolkit is no-auth
+     * Set to false to disable the workbench entirely. When disabled, no code execution
+     * tools are available in the session.
      */
-    is_no_auth: boolean;
+    enable?: boolean;
 
     /**
-     * Toolkit metadata
+     * Whether proxy execution is enabled. When enabled, workbench can call URLs and
+     * APIs directly.
      */
-    meta: Item.Meta;
+    enable_proxy_execution?: boolean;
 
     /**
-     * Display name of the toolkit
+     * 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.
      */
-    name: string;
+    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 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.
+   */
+  export interface Experimental {
     /**
-     * Unique slug identifier
+     * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+     * existing Composio toolkits. All tools are no-auth.
      */
-    slug: string;
-  }
+    custom_toolkits?: Array<Experimental.CustomToolkit>;
 
-  export namespace Item {
     /**
-     * Connected account if available
+     * Custom tools to include in search. Standalone tools need no auth. Tools with
+     * extends_toolkit inherit the Composio toolkit's connection.
      */
-    export interface ConnectedAccount {
-      /**
-       * Connected account identifier
-       */
-      id: string;
+    custom_tools?: Array<Experimental.CustomTool>;
+  }
 
+  export namespace Experimental {
+    export interface CustomToolkit {
       /**
-       * Auth config details
+       * Used for BM25 search matching and shown in toolkit connection statuses.
        */
-      auth_config: ConnectedAccount.AuthConfig;
+      description: string;
 
       /**
-       * Creation timestamp
+       * Display name shown to the LLM and in search results.
        */
-      created_at: string;
+      name: string;
 
       /**
-       * Connection status
+       * Unique slug for the toolkit. Must not conflict with existing Composio toolkit
+       * slugs. Alphanumeric, underscores, and hyphens only.
        */
-      status: string;
+      slug: string;
 
       /**
-       * User identifier
+       * Tools in this custom toolkit
        */
-      user_id: string;
+      tools: Array<CustomToolkit.Tool>;
     }
 
-    export namespace ConnectedAccount {
-      /**
-       * Auth config details
-       */
-      export interface AuthConfig {
+    export namespace CustomToolkit {
+      export interface Tool {
         /**
-         * Auth config identifier
+         * Used for BM25 search matching and shown to the LLM.
          */
-        id: string;
+        description: string;
 
         /**
-         * Authentication scheme type
+         * Must have type: "object" and a properties field.
          */
-        auth_scheme: string;
+        input_schema: { [key: string]: unknown };
 
         /**
-         * Whether this is a Composio-managed auth config
+         * Human-readable display name
          */
-        is_composio_managed: boolean;
+        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 };
       }
     }
 
-    /**
-     * Toolkit metadata
-     */
-    export interface Meta {
+    export interface CustomTool {
       /**
-       * Description of the toolkit
+       * Used for BM25 search matching and shown to the LLM.
        */
       description: string;
 
       /**
-       * URL to the toolkit logo
+       * Must have type: "object" and a properties field.
        */
-      logo: string;
+      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 SessionToolsResponse {
+export interface SessionConfigHistoryParams {
   /**
-   * List of tools with their complete schemas
+   * 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.
    */
-  items: Array<SessionToolsResponse.Item>;
-}
-
-export namespace SessionToolsResponse {
-  export 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;
+  cursor?: string;
 
-    /**
-     * Schema definition of return values from the tool
-     */
-    output_parameters: { [key: string]: unknown };
+  /**
+   * Number of items per page, max allowed is 100
+   */
+  limit?: number;
+}
 
-    /**
-     * Structured scope requirements for the tool. Null means the tool is legacy and
-     * only exposes flat scopes.
-     */
-    scope_requirements: Item.ScopeRequirements | null;
+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;
 
-    /**
-     * List of scopes associated with the tool
-     */
-    scopes: Array<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;
 
-    /**
-     * Unique identifier for the tool
-     */
-    slug: string;
+  /**
+   * The arguments required by the tool
+   */
+  arguments?: { [key: string]: unknown };
 
-    /**
-     * List of tags associated with the tool for categorization and filtering
-     */
-    tags: Array<string>;
+  /**
+   * 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;
 
-    toolkit: Item.Toolkit;
+  /**
+   * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+   * customs — pass them on every request that needs them.
+   */
+  experimental?: SessionExecuteParams.Experimental;
+}
 
+export namespace SessionExecuteParams {
+  /**
+   * Inline custom tools and toolkits for this request. v3.1 sessions do not persist
+   * customs — pass them on every request that needs them.
+   */
+  export interface Experimental {
     /**
-     * Current version of the tool
+     * Custom toolkits with grouped tools. Toolkit slugs must not conflict with
+     * existing Composio toolkits. All tools are no-auth.
      */
-    version: string;
+    custom_toolkits?: Array<Experimental.CustomToolkit>;
 
     /**
-     * Human-friendly description of the tool, if available
+     * Custom tools to include in search. Standalone tools need no auth. Tools with
+     * extends_toolkit inherit the Composio toolkit's connection.
      */
-    human_description?: string;
+    custom_tools?: Array<Experimental.CustomTool>;
   }
 
-  export namespace Item {
-    export interface Deprecated {
+  export namespace Experimental {
+    export 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>;
     }
 
-    export namespace Deprecated {
-      export interface Toolkit {
+    export namespace CustomToolkit {
+      export interface Tool {
         /**
-         * URL to the toolkit logo image
+         * Used for BM25 search matching and shown to the LLM.
          */
-        logo: string;
-      }
-    }
+        description: string;
 
-    /**
-     * Structured scope requirements for the tool. Null means the tool is legacy and
-     * only exposes flat scopes.
-     */
-    export interface ScopeRequirements {
-      all_of: Array<string | ScopeRequirements.AnyOf>;
-    }
+        /**
+         * Must have type: "object" and a properties field.
+         */
+        input_schema: { [key: string]: unknown };
 
-    export namespace ScopeRequirements {
-      export interface AnyOf {
-        any_of: Array<string>;
+        /**
+         * 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 };
       }
     }
 
-    export interface Toolkit {
+    export 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 {
-  /**
-   * 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 };
-
-  /**
-   * 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. 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?: SessionCreateParams.Preload;
-
-  /**
-   * 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;
-
+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 namespace SessionCreateParams {
+export 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.
    */
   export 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.
@@ -1723,26 +3426,9 @@ export namespace SessionCreateParams {
      * 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.
-     */
-    permissions?: Experimental.Permissions;
   }
 
   export namespace Experimental {
-    /**
-     * Customize assistive prompt generation (e.g., timezone).
-     */
-    export 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;
-    }
-
     export interface CustomToolkit {
       /**
        * Used for BM25 search matching and shown in toolkit connection statuses.
@@ -1802,37 +3488,130 @@ export namespace SessionCreateParams {
        */
       description: string;
 
-      /**
-       * Must have type: "object" and a properties field.
-       */
-      input_schema: { [key: string]: unknown };
+      /**
+       * 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 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;
 
-      /**
-       * Human-readable display name
-       */
-      name: string;
+  /**
+   * 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 };
 
-      /**
-       * Tool slug. Forms LOCAL*<TOOL> (standalone) or LOCAL*<TOOLKIT>\_<TOOL>
-       * (extending). Max 60 chars total.
-       */
-      slug: string;
+  workbench?: SessionPatchParams.Workbench | null;
+}
 
-      /**
-       * 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;
+export namespace SessionPatchParams {
+  export interface Execute {
+    enable_multi_execute?: boolean;
+  }
 
-      /**
-       * JSON Schema describing tool output (optional)
-       */
-      output_schema?: { [key: string]: unknown };
-    }
+  export interface Experimental {
+    /**
+     * Per-tool elicitation permission config. Replaces the stored block when provided.
+     */
+    permissions?: Experimental.Permissions;
+  }
 
+  export namespace 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.
      */
     export interface Permissions {
       /**
@@ -1844,17 +3623,18 @@ export 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' };
+      overrides?: { [key: string]: 'always_allow' | 'always_deny' | 'ask_once' | 'ask_always' };
     }
   }
 
-  /**
-   * Configuration for connection management settings
-   */
   export interface ManageConnections {
     /**
      * The URL to redirect to after a user completes authentication for a connected
@@ -1884,10 +3664,6 @@ export namespace SessionCreateParams {
     enable_wait_for_connections?: boolean | null;
   }
 
-  /**
-   * Configure multi-account behavior. When enabled, users can connect multiple
-   * accounts per toolkit.
-   */
   export interface MultiAccount {
     /**
      * When true, enables multi-account mode for this session. When not set, falls back
@@ -1909,23 +3685,21 @@ export namespace SessionCreateParams {
   }
 
   /**
-   * 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.
    */
   export 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;
+  }
+
+  export interface Search {
+    enable?: boolean;
   }
 
   export interface UnionMember1 {
@@ -1984,9 +3758,6 @@ export namespace SessionCreateParams {
     }
   }
 
-  /**
-   * Configuration for workbench behavior
-   */
   export interface Workbench {
     /**
      * Character threshold for automatic offloading. When workbench response exceeds
@@ -2009,83 +3780,13 @@ export namespace SessionCreateParams {
 
     /**
      * 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
@@ -2945,13 +4646,18 @@ export 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;
 }
@@ -2970,6 +4676,113 @@ export 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.
+   */
+  export 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>;
+  }
+
+  export namespace Experimental {
+    export 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>;
+    }
+
+    export namespace CustomToolkit {
+      export 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 };
+      }
+    }
+
+    export 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 {
@@ -3004,7 +4817,20 @@ export interface SessionToolkitsParams {
   toolkits?: Array<string> | null;
 }
 
-export interface SessionToolsParams {}
+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;
+}
 
 Session.Files = Files;
 
@@ -3012,17 +4838,23 @@ export declare namespace Session {
   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,