@composio/client 0.1.0-alpha.6 → 0.1.0-alpha.61

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

@@ -0,0 +1,1465 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../../core/resource';
+import * as FilesAPI from './files';
+import {
+  FileCreateDownloadURLParams,
+  FileCreateDownloadURLResponse,
+  FileCreateUploadURLParams,
+  FileCreateUploadURLResponse,
+  FileDeleteParams,
+  FileDeleteResponse,
+  FileListParams,
+  FileListResponse,
+  Files,
+} from './files';
+import { APIPromise } from '../../../core/api-promise';
+import { RequestOptions } from '../../../internal/request-options';
+import { path } from '../../../internal/utils/path';
+
+/**
+ * (Labs) Tool router endpoints
+ */
+export class Session extends APIResource {
+  files: FilesAPI.Files = new FilesAPI.Files(this._client);
+
+  /**
+   * Creates a new session for the tool router feature. This endpoint initializes a
+   * new session with specified toolkits and their authentication configurations. The
+   * session provides an isolated environment for testing and managing tool routing
+   * logic with scoped MCP server access.
+   *
+   * @example
+   * ```ts
+   * const session = await client.toolRouter.session.create({
+   *   user_id: 'user_123456789',
+   * });
+   * ```
+   */
+  create(body: SessionCreateParams, options?: RequestOptions): APIPromise<SessionCreateResponse> {
+    return this._client.post('/api/v3/tool_router/session', { body, ...options });
+  }
+
+  /**
+   * Retrieves an existing tool router session by its ID. Returns the session
+   * configuration, MCP server URL, and available tools.
+   *
+   * @example
+   * ```ts
+   * const session = await client.toolRouter.session.retrieve(
+   *   'trs_123456789',
+   * );
+   * ```
+   */
+  retrieve(sessionID: string, options?: RequestOptions): APIPromise<SessionRetrieveResponse> {
+    return this._client.get(path`/api/v3/tool_router/session/${sessionID}`, options);
+  }
+
+  /**
+   * Executes a specific tool within a tool router session. The toolkit is
+   * automatically inferred from the tool slug. The tool must belong to an allowed
+   * toolkit and must not be disabled in the session configuration. This endpoint
+   * validates permissions, resolves connected accounts, and executes the tool with
+   * the session context.
+   *
+   * @example
+   * ```ts
+   * const response = await client.toolRouter.session.execute(
+   *   'trs_LX9uJKBinWWr',
+   *   { tool_slug: 'GITHUB_CREATE_ISSUE' },
+   * );
+   * ```
+   */
+  execute(
+    sessionID: string,
+    body: SessionExecuteParams,
+    options?: RequestOptions,
+  ): APIPromise<SessionExecuteResponse> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute`, { body, ...options });
+  }
+
+  /**
+   * Executes a Composio meta tool (COMPOSIO\_\*) within a tool router session.
+   *
+   * @example
+   * ```ts
+   * const response =
+   *   await client.toolRouter.session.executeMeta(
+   *     'trs_LX9uJKBinWWr',
+   *     { slug: 'COMPOSIO_MANAGE_CONNECTIONS' },
+   *   );
+   * ```
+   */
+  executeMeta(
+    sessionID: string,
+    body: SessionExecuteMetaParams,
+    options?: RequestOptions,
+  ): APIPromise<SessionExecuteMetaResponse> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/execute_meta`, {
+      body,
+      ...options,
+    });
+  }
+
+  /**
+   * Initiates an authentication link session for a specific toolkit within a tool
+   * router session. Returns a link token and redirect URL that users can use to
+   * complete the OAuth flow.
+   *
+   * @example
+   * ```ts
+   * const response = await client.toolRouter.session.link(
+   *   'trs_LX9uJKBinWWr',
+   *   { toolkit: 'github' },
+   * );
+   * ```
+   */
+  link(
+    sessionID: string,
+    body: SessionLinkParams,
+    options?: RequestOptions,
+  ): APIPromise<SessionLinkResponse> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/link`, { 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.
+   *
+   * @example
+   * ```ts
+   * const response = await client.toolRouter.session.search(
+   *   'trs_LX9uJKBinWWr',
+   *   {
+   *     queries: [
+   *       { use_case: 'Send a slack message to a channel' },
+   *     ],
+   *   },
+   * );
+   * ```
+   */
+  search(
+    sessionID: string,
+    body: SessionSearchParams,
+    options?: RequestOptions,
+  ): APIPromise<SessionSearchResponse> {
+    return this._client.post(path`/api/v3/tool_router/session/${sessionID}/search`, { body, ...options });
+  }
+
+  /**
+   * Retrieves a cursor-paginated list of toolkits available in the tool router
+   * session. Includes toolkit metadata, composio-managed auth schemes, and connected
+   * accounts if available. Optionally filter by specific toolkit slugs.
+   *
+   * @example
+   * ```ts
+   * const response = await client.toolRouter.session.toolkits(
+   *   'trs_123456789',
+   * );
+   * ```
+   */
+  toolkits(
+    sessionID: string,
+    query: SessionToolkitsParams | null | undefined = {},
+    options?: RequestOptions,
+  ): APIPromise<SessionToolkitsResponse> {
+    return this._client.get(path`/api/v3/tool_router/session/${sessionID}/toolkits`, { query, ...options });
+  }
+
+  /**
+   * Returns the meta tools available in a tool router session with their complete
+   * schemas. This includes request and response schemas specific to the session
+   * context.
+   *
+   * @example
+   * ```ts
+   * const response = await client.toolRouter.session.tools(
+   *   'session_id',
+   * );
+   * ```
+   */
+  tools(
+    sessionID: string,
+    query?: SessionToolsParams | null | undefined,
+    options?: RequestOptions,
+  ): APIPromise<SessionToolsResponse> {
+    return this._client.get(path`/api/v3/tool_router/session/${sessionID}/tools`, options);
+  }
+}
+
+export interface SessionCreateResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  config: SessionCreateResponse.Config;
+
+  mcp: SessionCreateResponse.Mcp;
+
+  /**
+   * The identifier of the session
+   */
+  session_id: string;
+
+  /**
+   * List of available tools in this session
+   */
+  tool_router_tools: Array<string>;
+
+  /**
+   * Experimental features including the generated system prompt. Only returned on
+   * session creation, not on GET.
+   */
+  experimental?: SessionCreateResponse.Experimental;
+}
+
+export namespace SessionCreateResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  export interface Config {
+    /**
+     * User identifier for this session
+     */
+    user_id: string;
+
+    /**
+     * Auth config overrides per toolkit
+     */
+    auth_configs?: { [key: string]: string };
+
+    /**
+     * Connected account overrides per toolkit
+     */
+    connected_accounts?: { [key: string]: string };
+
+    /**
+     * Manage connections configuration
+     */
+    manage_connections?: Config.ManageConnections;
+
+    /**
+     * 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 {
+    /**
+     * Manage connections configuration
+     */
+    export interface ManageConnections {
+      /**
+       * Custom callback URL for connected account auth flows
+       */
+      callback_url?: string;
+
+      /**
+       * 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;
+    }
+
+    /**
+     * 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 proxy execution is enabled in the workbench
+       */
+      proxy_execution_enabled?: boolean;
+    }
+  }
+
+  export interface Mcp {
+    /**
+     * The type of the MCP server. Can be http
+     */
+    type: 'http';
+
+    /**
+     * The URL of the MCP server
+     */
+    url: string;
+  }
+
+  /**
+   * Experimental features including the generated system prompt. Only returned on
+   * session creation, not on GET.
+   */
+  export interface Experimental {
+    /**
+     * The assistive system prompt to inject into your agent for optimal tool router
+     * usage
+     */
+    assistive_prompt: string;
+  }
+}
+
+export interface SessionRetrieveResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  config: SessionRetrieveResponse.Config;
+
+  mcp: SessionRetrieveResponse.Mcp;
+
+  /**
+   * The identifier of the session
+   */
+  session_id: string;
+
+  /**
+   * List of available tools in this session
+   */
+  tool_router_tools: Array<string>;
+}
+
+export namespace SessionRetrieveResponse {
+  /**
+   * The session configuration including user, toolkits, and overrides
+   */
+  export interface Config {
+    /**
+     * User identifier for this session
+     */
+    user_id: string;
+
+    /**
+     * Auth config overrides per toolkit
+     */
+    auth_configs?: { [key: string]: string };
+
+    /**
+     * Connected account overrides per toolkit
+     */
+    connected_accounts?: { [key: string]: string };
+
+    /**
+     * Manage connections configuration
+     */
+    manage_connections?: Config.ManageConnections;
+
+    /**
+     * 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 {
+    /**
+     * Manage connections configuration
+     */
+    export interface ManageConnections {
+      /**
+       * Custom callback URL for connected account auth flows
+       */
+      callback_url?: string;
+
+      /**
+       * 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;
+    }
+
+    /**
+     * 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 proxy execution is enabled in the workbench
+       */
+      proxy_execution_enabled?: boolean;
+    }
+  }
+
+  export interface Mcp {
+    /**
+     * The type of the MCP server. Can be http
+     */
+    type: 'http';
+
+    /**
+     * The URL of the MCP server
+     */
+    url: string;
+  }
+}
+
+export interface SessionExecuteResponse {
+  /**
+   * The data returned by the tool execution
+   */
+  data: { [key: string]: unknown };
+
+  /**
+   * Error message if the execution failed, null otherwise
+   */
+  error: string | null;
+
+  /**
+   * Unique identifier for the execution log
+   */
+  log_id: string;
+}
+
+export interface SessionExecuteMetaResponse {
+  /**
+   * The data returned by the tool execution
+   */
+  data: { [key: string]: unknown };
+
+  /**
+   * Error message if the execution failed, null otherwise
+   */
+  error: string | null;
+
+  /**
+   * Unique identifier for the execution log
+   */
+  log_id: string;
+}
+
+export interface SessionLinkResponse {
+  /**
+   * The unique identifier for the connected account
+   */
+  connected_account_id: string;
+
+  /**
+   * 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 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
+     */
+    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;
+
+      /**
+       * Instruction message for the LLM
+       */
+      message: string;
+
+      /**
+       * Tool to call
+       */
+      tool: 'COMPOSIO_GET_TOOL_SCHEMAS';
+    }
+
+    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;
+
+    /**
+     * 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 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 {
+  /**
+   * List of tools with their complete schemas
+   */
+  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;
+
+    /**
+     * Schema definition of return values from the tool
+     */
+    output_parameters: { [key: string]: unknown };
+
+    /**
+     * 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;
+      }
+    }
+
+    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
+   */
+  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;
+
+  /**
+   * 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 - either specify enable tools (whitelist),
+   * disable tools (blacklist), or filter by MCP tags for each toolkit
+   */
+  tools?: {
+    [key: string]: SessionCreateParams.Enable | SessionCreateParams.Disable | SessionCreateParams.Tags;
+  };
+
+  /**
+   * Configuration for workbench behavior
+   */
+  workbench?: SessionCreateParams.Workbench;
+}
+
+export namespace SessionCreateParams {
+  /**
+   * 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;
+  }
+
+  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;
+    }
+  }
+
+  /**
+   * 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;
+
+    /**
+     * 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;
+  }
+
+  export interface UnionMember1 {
+    /**
+     * Tags that the tool must NOT have any of
+     */
+    disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+
+    /**
+     * Tags that the tool must have at least one of
+     */
+    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 {
+      /**
+       * Tags that the tool must NOT have any of
+       */
+      disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+
+      /**
+       * Tags that the tool must have at least one of
+       */
+      enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
+    }
+  }
+
+  /**
+   * Configuration for workbench behavior
+   */
+  export interface Workbench {
+    /**
+     * Character threshold for automatic offloading. When workbench response exceeds
+     * this threshold, it will be automatically offloaded. Default is picked
+     * automatically based on the response size.
+     */
+    auto_offload_threshold?: number;
+
+    /**
+     * Whether proxy execution is enabled. When enabled, workbench can call URLs and
+     * APIs directly.
+     */
+    enable_proxy_execution?: boolean;
+  }
+}
+
+export interface SessionExecuteParams {
+  /**
+   * The unique slug identifier of the tool to execute
+   */
+  tool_slug: string;
+
+  /**
+   * The arguments required by the tool
+   */
+  arguments?: { [key: string]: unknown };
+}
+
+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;
+
+  /**
+   * URL where users will be redirected after completing auth
+   */
+  callback_url?: string;
+}
+
+export interface SessionSearchParams {
+  /**
+   * List of search queries to execute in parallel. Up to 7 queries supported.
+   */
+  queries: Array<SessionSearchParams.Query>;
+
+  /**
+   * Optional model hint for search/planning behavior (e.g., "gpt-4o"). Ignored if
+   * invalid.
+   */
+  model?: string;
+}
+
+export namespace SessionSearchParams {
+  export interface Query {
+    /**
+     * The task or use case to search tools for. Provide a detailed description to get
+     * the best results.
+     */
+    use_case: string;
+
+    /**
+     * Known field hints as key:value pairs (e.g., "channel_name:general,
+     * user_email:john@example.com")
+     */
+    known_fields?: string;
+  }
+}
+
+export interface SessionToolkitsParams {
+  /**
+   * 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;
+
+  /**
+   * Whether to filter by connected toolkits. If provided, only connected toolkits
+   * will be returned.
+   */
+  is_connected?: boolean | null;
+
+  /**
+   * Number of items per page, max allowed is 1000
+   */
+  limit?: number | null;
+
+  /**
+   * Search query to filter toolkits by name, slug, or description
+   */
+  search?: string;
+
+  /**
+   * Optional comma-separated list of toolkit slugs to filter by. If provided, only
+   * these toolkits will be returned, overriding the session configuration.
+   */
+  toolkits?: Array<string> | null;
+}
+
+export interface SessionToolsParams {}
+
+Session.Files = Files;
+
+export declare namespace Session {
+  export {
+    type SessionCreateResponse as SessionCreateResponse,
+    type SessionRetrieveResponse as SessionRetrieveResponse,
+    type SessionExecuteResponse as SessionExecuteResponse,
+    type SessionExecuteMetaResponse as SessionExecuteMetaResponse,
+    type SessionLinkResponse as SessionLinkResponse,
+    type SessionSearchResponse as SessionSearchResponse,
+    type SessionToolkitsResponse as SessionToolkitsResponse,
+    type SessionToolsResponse as SessionToolsResponse,
+    type SessionCreateParams as SessionCreateParams,
+    type SessionExecuteParams as SessionExecuteParams,
+    type SessionExecuteMetaParams as SessionExecuteMetaParams,
+    type SessionLinkParams as SessionLinkParams,
+    type SessionSearchParams as SessionSearchParams,
+    type SessionToolkitsParams as SessionToolkitsParams,
+    type SessionToolsParams as SessionToolsParams,
+  };
+
+  export {
+    Files as Files,
+    type FileListResponse as FileListResponse,
+    type FileDeleteResponse as FileDeleteResponse,
+    type FileCreateDownloadURLResponse as FileCreateDownloadURLResponse,
+    type FileCreateUploadURLResponse as FileCreateUploadURLResponse,
+    type FileListParams as FileListParams,
+    type FileDeleteParams as FileDeleteParams,
+    type FileCreateDownloadURLParams as FileCreateDownloadURLParams,
+    type FileCreateUploadURLParams as FileCreateUploadURLParams,
+  };
+}