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

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

@@ -47,7 +47,7 @@ export class Session extends APIResource {
    * @example
    * ```ts
    * const session = await client.toolRouter.session.retrieve(
-   *   'trs_123456789',
+   *   'trs_1a2b3c4d5e6f',
    * );
    * ```
    */
@@ -56,11 +56,16 @@ export class Session extends APIResource {
   }
 
   /**
-   * 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.
+   * 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.
    *
    * @example
    * ```ts
@@ -79,7 +84,9 @@ export class Session extends APIResource {
   }
 
   /**
-   * Executes a Composio meta tool (COMPOSIO\_\*) within a tool router session.
+   * 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.
    *
    * @example
    * ```ts
@@ -188,7 +195,7 @@ export class Session extends APIResource {
    * @example
    * ```ts
    * const response = await client.toolRouter.session.toolkits(
-   *   'trs_123456789',
+   *   'trs_1a2b3c4d5e6f',
    * );
    * ```
    */
@@ -201,9 +208,9 @@ export class Session extends APIResource {
   }
 
   /**
-   * 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.
+   * 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.
    *
    * @example
    * ```ts
@@ -227,6 +234,12 @@ export interface SessionCreateResponse {
    */
   config: SessionCreateResponse.Config;
 
+  /**
+   * Monotonic version of the config. Incremented on each PATCH. Use for optimistic
+   * concurrency control.
+   */
+  config_version: number;
+
   mcp: SessionCreateResponse.Mcp;
 
   /**
@@ -244,6 +257,12 @@ export interface SessionCreateResponse {
    * session creation, not on GET.
    */
   experimental?: SessionCreateResponse.Experimental;
+
+  /**
+   * Advisory list — the session exists and is usable, but the listed issues may
+   * warrant attention.
+   */
+  warnings?: Array<SessionCreateResponse.Warning>;
 }
 
 export namespace SessionCreateResponse {
@@ -251,6 +270,15 @@ export namespace SessionCreateResponse {
    * The session configuration including user, toolkits, and overrides
    */
   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).
+     */
+    preload: Config.Preload;
+
     /**
      * User identifier for this session
      */
@@ -262,7 +290,8 @@ export namespace SessionCreateResponse {
     auth_configs?: { [key: string]: string };
 
     /**
-     * Connected account overrides per toolkit
+     * Connected account overrides per toolkit. Each connected account must belong to
+     * the same user_id as the session.
      */
     connected_accounts?: { [key: string]: string };
 
@@ -271,6 +300,11 @@ export namespace SessionCreateResponse {
      */
     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
@@ -295,6 +329,22 @@ 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).
+     */
+    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.
+       */
+      tools: Array<string>;
+    }
+
     /**
      * Manage connections configuration
      */
@@ -321,6 +371,29 @@ export namespace SessionCreateResponse {
       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
@@ -392,6 +465,12 @@ export namespace SessionCreateResponse {
        * 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';
     }
   }
 
@@ -483,6 +562,19 @@ export namespace SessionCreateResponse {
       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 SessionRetrieveResponse {
@@ -491,6 +583,12 @@ export interface SessionRetrieveResponse {
    */
   config: SessionRetrieveResponse.Config;
 
+  /**
+   * Monotonic version of the config. Incremented on each PATCH. Use for optimistic
+   * concurrency control.
+   */
+  config_version: number;
+
   mcp: SessionRetrieveResponse.Mcp;
 
   /**
@@ -507,6 +605,12 @@ export interface SessionRetrieveResponse {
    * Experimental features
    */
   experimental?: SessionRetrieveResponse.Experimental;
+
+  /**
+   * Advisory list — the session exists and is usable, but the listed issues may
+   * warrant attention.
+   */
+  warnings?: Array<SessionRetrieveResponse.Warning>;
 }
 
 export namespace SessionRetrieveResponse {
@@ -514,6 +618,15 @@ export namespace SessionRetrieveResponse {
    * The session configuration including user, toolkits, and overrides
    */
   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).
+     */
+    preload: Config.Preload;
+
     /**
      * User identifier for this session
      */
@@ -525,7 +638,8 @@ export namespace SessionRetrieveResponse {
     auth_configs?: { [key: string]: string };
 
     /**
-     * Connected account overrides per toolkit
+     * Connected account overrides per toolkit. Each connected account must belong to
+     * the same user_id as the session.
      */
     connected_accounts?: { [key: string]: string };
 
@@ -534,6 +648,11 @@ export namespace SessionRetrieveResponse {
      */
     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
@@ -558,6 +677,22 @@ 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).
+     */
+    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.
+       */
+      tools: Array<string>;
+    }
+
     /**
      * Manage connections configuration
      */
@@ -584,6 +719,29 @@ export namespace SessionRetrieveResponse {
       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
@@ -655,6 +813,12 @@ export namespace SessionRetrieveResponse {
        * 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';
     }
   }
 
@@ -745,6 +909,19 @@ export namespace SessionRetrieveResponse {
       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 SessionExecuteResponse {
@@ -1456,7 +1633,9 @@ export interface SessionCreateParams {
   /**
    * 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
+   * 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 };
 
@@ -1477,6 +1656,18 @@ export interface SessionCreateParams {
    */
   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)
@@ -1494,8 +1685,11 @@ export interface SessionCreateParams {
   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
+   * 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;
@@ -1529,6 +1723,12 @@ 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 {
@@ -1629,6 +1829,27 @@ export namespace SessionCreateParams {
        */
       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__"}`.
+       * `always_allow` skips the prompt and runs the tool; `always_deny` blocks the
+       * tool. Overrides take precedence over `default` and the session cache.
+       */
+      overrides?: { [key: string]: 'always_allow' | 'always_deny' };
+    }
   }
 
   /**
@@ -1687,15 +1908,29 @@ export namespace SessionCreateParams {
     require_explicit_selection?: boolean;
   }
 
-  export interface UnionMember1 {
+  /**
+   * 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.
+   */
+  export interface Preload {
     /**
-     * Tags that the tool must NOT have any of
+     * 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.
      */
+    tools?: Array<string>;
+  }
+
+  export interface UnionMember1 {
     disable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
 
-    /**
-     * Tags that the tool must have at least one of
-     */
     enable?: Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>;
   }
 
@@ -1743,14 +1978,8 @@ export namespace SessionCreateParams {
 
   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'>;
     }
   }
@@ -1777,20 +2006,29 @@ export namespace SessionCreateParams {
      * APIs directly.
      */
     enable_proxy_execution?: boolean;
+
+    /**
+     * Sandbox compute tier: standard (1 vCPU / 1 GB), medium (2 vCPU / 2 GB), large (4
+     * vCPU / 4 GB), xlarge (8 vCPU / 8 GB). Defaults to standard.
+     */
+    sandbox_size?: 'standard' | 'medium' | 'large' | 'xlarge';
   }
 }
 
 export interface SessionExecuteParams {
   /**
-   * The unique slug identifier of the tool to execute
+   * 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. 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.
+   * 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;
 
@@ -1798,6 +2036,15 @@ export interface SessionExecuteParams {
    * 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 {
@@ -2713,13 +2960,13 @@ export namespace SessionSearchParams {
   export interface Query {
     /**
      * The task or use case to search tools for. Provide a detailed description to get
-     * the best results.
+     * the best results. Max 1024 characters.
      */
     use_case: string;
 
     /**
      * Known field hints as key:value pairs (e.g., "channel_name:general,
-     * user_email:john@example.com")
+     * user_email:john@example.com"). Max 500 characters.
      */
     known_fields?: string;
   }

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

@@ -72,7 +72,7 @@ export interface ToolRouterCreateSessionResponse {
   chat_session_mcp_url: string;
 
   /**
-   * Generated session identifier
+   * Generated session identifier (prefixed with "trs\_")
    */
   session_id: string;
 

package/src/version.ts

@@ -1 +1 @@
-export const VERSION = '0.1.0-alpha.66'; // x-release-please-version
+export const VERSION = '0.1.0-alpha.68'; // x-release-please-version

package/version.d.mts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-alpha.66";
+export declare const VERSION = "0.1.0-alpha.68";
 //# sourceMappingURL=version.d.mts.map

package/version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.1.0-alpha.66";
+export declare const VERSION = "0.1.0-alpha.68";
 //# sourceMappingURL=version.d.ts.map

package/version.js

@@ -1,5 +1,5 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
-exports.VERSION = '0.1.0-alpha.66'; // x-release-please-version
+exports.VERSION = '0.1.0-alpha.68'; // x-release-please-version
 //# sourceMappingURL=version.js.map

package/version.mjs

@@ -1,2 +1,2 @@
-export const VERSION = '0.1.0-alpha.66'; // x-release-please-version
+export const VERSION = '0.1.0-alpha.68'; // x-release-please-version
 //# sourceMappingURL=version.mjs.map