Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
support preloaded custom tool schemas
Dhawal Upadhyaya2db64a1503c
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 154ae7dc5..b4664ec56 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -610,6 +610,7 @@ def build_custom_tools_map(handle: CustomTool, final_slug: str, toolkit: t.Optional[str]) -> None:original_slug = handle.slug.upper()+ final_slug_key = final_slug.upper()if len(final_slug) > MAX_SLUG_LENGTH:raise ValidationError(@@ -617,7 +618,7 @@ def build_custom_tools_map(f'"{final_slug}" which exceeds {MAX_SLUG_LENGTH} characters.')- if final_slug in by_final_slug:+ if final_slug_key in by_final_slug:raise ValidationError(f'Custom tool slug collision: "{final_slug}" is already registered.')@@ -634,7 +635,7 @@ def build_custom_tools_map(entry = CustomToolsMapEntry(handle=handle, final_slug=final_slug, toolkit=toolkit)- by_final_slug[final_slug] = entry+ by_final_slug[final_slug_key] = entryby_original_slug[original_slug] = entry# Process standalone tools@@ -716,3 +717,42 @@ def build_custom_tools_map_from_response(by_original_slug=by_original_slug,toolkits=list(toolkits) if toolkits else None,)+++def find_custom_tool_map_entry_by_final_slug(+ custom_tools_map: t.Optional[CustomToolsMap],+ slug: str,+) -> t.Optional[CustomToolsMapEntry]:+ """Find a custom tool entry by final slug only."""+ if custom_tools_map is None:+ return None+ return custom_tools_map.by_final_slug.get(slug.upper())+++def get_preloaded_custom_tool_slugs(+ tool_router_tools: t.Optional[t.Iterable[str]],+ custom_tools_map: t.Optional[CustomToolsMap],+) -> t.List[str]:+ """Return final custom tool slugs selected by the backend for preload."""+ if tool_router_tools is None or custom_tools_map is None:+ return []++ seen: t.Set[str] = set()+ custom_tool_slugs: t.List[str] = []++ for slug in tool_router_tools:+ entry = find_custom_tool_map_entry_by_final_slug(+ custom_tools_map,+ str(slug),+ )+ if entry is None:+ continue++ final_slug_key = entry.final_slug.upper()+ if final_slug_key in seen:+ continue++ seen.add(final_slug_key)+ custom_tool_slugs.append(entry.final_slug)++ return custom_tool_slugsdiff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex a460ed503..d8392d4e6 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -20,6 +20,7 @@ from composio.core.models.base import Resourcefrom composio.core.models.custom_tool import (ExperimentalToolkit,build_custom_tools_map_from_response,+ get_preloaded_custom_tool_slugs,serialize_custom_tools,serialize_custom_toolkits,)@@ -51,6 +52,7 @@ ToolRouterTag = t.Literal[# +----------+------+------+# Defaults to "standard" server-side when omitted.SandboxSize = t.Literal["standard", "medium", "large", "xlarge"]+SessionPreset = t.Literal["direct_tools"]class ToolRouterToolkitsEnableConfig(te.TypedDict, total=False):@@ -217,7 +219,34 @@ class ToolRouterPreloadConfig(te.TypedDict, total=False):tool lists without first calling search."""- tools: t.List[str]+ tools: t.Union[t.List[str], str]+++def _session_preload_config(session: t.Any) -> ToolRouterSessionPreloadConfig:+ tools = session.config.preload.tools+ return ToolRouterSessionPreloadConfig(+ tools=tools if isinstance(tools, str) else list(tools or [])+ )+++def _apply_session_preset_defaults(+ session_preset: t.Optional[SessionPreset],+ manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],+ workbench: t.Optional[ToolRouterWorkbenchConfig],+ preload: t.Optional[ToolRouterPreloadConfig],+) -> t.Tuple[+ t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],+ t.Optional[ToolRouterWorkbenchConfig],+ t.Optional[ToolRouterPreloadConfig],+]:+ if session_preset != "direct_tools":+ return manage_connections, workbench, preload++ return (+ False if manage_connections is None else manage_connections,+ {"enable": False} if workbench is None else workbench,+ {"tools": "all"} if preload is None else preload,+ )class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):@@ -497,6 +526,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):workbench: t.Optional[ToolRouterWorkbenchConfig] = None,multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,preload: t.Optional[ToolRouterPreloadConfig] = None,+ session_preset: t.Optional[SessionPreset] = None,experimental: t.Optional[ToolRouterExperimentalConfig] = None,) -> ToolRouterSession[TTool, TToolCollection]:"""@@ -553,8 +583,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):Example: {'github': 'ac_xxx', 'slack': 'ac_yyy'}:param connected_accounts: Optional mapping of toolkit slug to connected account ID.Example: {'github': 'ca_xxx', 'slack': 'ca_yyy'}- :param workbench: Optional workbench configuration (ToolRouterWorkbenchConfig).- Dict with:+ :param workbench: Optional workbench configuration. Dict with:- 'enable' (bool): Whether to enable the workbench entirely.Defaults to True. When set to False, no code execution tools(COMPOSIO_REMOTE_WORKBENCH, COMPOSIO_REMOTE_BASH_TOOL) are@@ -579,9 +608,19 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):account selection when multiple accounts are connected.Example: {'enable': True, 'max_accounts_per_toolkit': 3}:param preload: Optional preload configuration. Dict with:- - 'tools' (List[str]): Tool slugs to expose directly in- session.tools() and MCP tool lists.+ - 'tools' (List[str] | 'all'): Tool slugs to expose directly in+ session.tools() and MCP tool lists. 'all' exposes every app+ tool allowed by positive session filters such as toolkits,+ tools, or tags; the backend validates and caps the final set.Example: {'tools': ['GMAIL_FETCH_EMAILS']}+ :param session_preset: Optional session preset. 'direct_tools' exposes all tools+ allowed by the session filters directly in session.tools()+ and the MCP tool list, and disables meta tools by default+ (search, multi-execute, manage-connections, and workbench).+ Use when all needed tools are known upfront and helper/meta+ tools are not needed. Without this preset, ToolRouter uses+ the default configuration with meta tools enabled. Loading+ many tools can increase model context usage.:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).Note: These features are experimental and may change.Dict with:@@ -670,6 +709,14 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):```"""+ direct_tools_preset = session_preset == "direct_tools"+ manage_connections, workbench, preload = _apply_session_preset_defaults(+ session_preset=session_preset,+ manage_connections=manage_connections,+ workbench=workbench,+ preload=preload,+ )+# Parse manage_connections configmanage_connections = (manage_connections if manage_connections is not None else True@@ -795,6 +842,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):if preload is not None:create_params["preload"] = preload+ if direct_tools_preset:+ create_params["search"] = {"enable": False}+ create_params["execute"] = {"enable_multi_execute": False}+# Build experimental config# Map SDK's experimental.assistive_prompt.user_timezone to API's# experimental.assistive_prompt_config.user_timezone@@ -845,6 +896,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):toolkits=custom_toolkits,experimental=session.experimental,)+ preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(+ getattr(session, "tool_router_tools", None),+ custom_tools_map,+ )# Transform experimental response:# API's assistive_prompt -> SDK's assistive_prompt@@ -873,9 +928,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):experimental=experimental_response,custom_tools_map=custom_tools_map,user_id=user_id,- preload=ToolRouterSessionPreloadConfig(- tools=list(session.config.preload.tools)- ),+ preload=_session_preload_config(session),+ preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,)def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:@@ -930,9 +984,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):url=session.mcp.url,),experimental=experimental_response,- preload=ToolRouterSessionPreloadConfig(- tools=list(session.config.preload.tools)- ),+ preload=_session_preload_config(session),)@@ -952,6 +1004,7 @@ __all__ = ["ToolRouterManageConnectionsConfig","ToolRouterWorkbenchConfig","SandboxSize",+ "SessionPreset","ToolRouterMultiAccountConfig","ToolRouterPreloadConfig","ToolRouterExperimentalConfig",diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex 720f89e5b..33b86603b 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -13,6 +13,12 @@ from concurrent.futures import ThreadPoolExecutorfrom dataclasses import dataclassfrom composio_client import omit+from composio.client.types import Tool+from composio_client.types.tool_list_response import (+ ItemDeprecated,+ ItemDeprecatedToolkit,+ ItemToolkit,+)from composio_client.types.tool_router.session_execute_response import (SessionExecuteResponse,)@@ -25,6 +31,7 @@ from composio_client.types.tool_router.session_search_response import (from composio.client import HttpClientfrom composio.core.models.connected_accounts import ConnectionRequest+from composio.core.models.custom_tool import find_custom_tool_map_entry_by_final_slugfrom composio.core.models.custom_tool_execution import (execute_custom_tool,find_custom_tool,@@ -48,6 +55,9 @@ if t.TYPE_CHECKING:)COMPOSIO_MULTI_EXECUTE_TOOL = "COMPOSIO_MULTI_EXECUTE_TOOL"+DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX = (+ "[Direct tool - call directly, no search or connection check needed beforehand.]"+)MAX_PARALLEL_WORKERS = 5@@ -55,7 +65,7 @@ MAX_PARALLEL_WORKERS = 5class ToolRouterSessionPreloadConfig:"""Preloaded tools configured for a tool router session."""- tools: t.List[str]+ tools: t.Union[t.List[str], str]class ToolRouterSession(t.Generic[TTool, TToolCollection]):@@ -94,6 +104,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):custom_tools_map: t.Optional[CustomToolsMap] = None,user_id: t.Optional[str] = None,preload: t.Optional[ToolRouterSessionPreloadConfig] = None,+ preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,) -> None:self._client = clientself._provider = provider@@ -107,6 +118,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):self.preload = preload or ToolRouterSessionPreloadConfig(tools=[])self._custom_tools_map = custom_tools_mapself._user_id = user_id+ self._preloaded_custom_tool_slugs = preloaded_custom_tool_slugs or []# Create singleton session context if custom tools are boundself._session_context: t.Optional[SessionContextImpl] = None@@ -168,6 +180,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):session_id=self.session_id,modifiers=modifiers,)+ router_tools = self._add_preloaded_custom_tools(router_tools, modifiers)for tool in router_tools:tool.input_parameters = (@@ -201,6 +214,95 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):),)+ def _add_preloaded_custom_tools(+ self,+ tools: t.List[Tool],+ modifiers: t.Optional["Modifiers"],+ ) -> t.List[Tool]:+ custom_tools = self._get_preloaded_custom_tool_schemas(modifiers)+ if not custom_tools:+ return tools++ existing_slugs = {tool.slug.upper() for tool in tools}+ appended_tools = [+ tool for tool in custom_tools if tool.slug.upper() not in existing_slugs+ ]+ if not appended_tools:+ return tools++ return [*tools, *appended_tools]++ def _get_preloaded_custom_tool_schemas(+ self,+ modifiers: t.Optional["Modifiers"],+ ) -> t.List[Tool]:+ if not self._custom_tools_map or not self._preloaded_custom_tool_slugs:+ return []++ tools: t.List[Tool] = []+ for slug in self._preloaded_custom_tool_slugs:+ entry = find_custom_tool_map_entry_by_final_slug(+ self._custom_tools_map,+ slug,+ )+ if entry is None:+ continue++ tool = self._custom_tool_entry_to_tool(entry)+ if modifiers is not None:+ tool = t.cast(+ Tool,+ apply_modifier_by_type(+ modifiers=modifiers,+ toolkit=tool.toolkit.slug,+ tool=tool.slug,+ type="schema",+ schema=tool,+ ),+ )+ tools.append(tool)++ return tools++ def _custom_tool_entry_to_tool(self, entry: CustomToolsMapEntry) -> Tool:+ toolkit_slug = entry.toolkit or "custom"+ toolkit_name = (+ self._custom_toolkit_name(toolkit_slug) or entry.toolkit or "Custom"+ )++ return Tool(+ available_versions=[],+ deprecated=ItemDeprecated(+ available_versions=[],+ displayName=entry.handle.name,+ is_deprecated=False,+ toolkit=ItemDeprecatedToolkit(logo=""),+ version="latest",+ ),+ description=(+ f"{DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX}\n{entry.handle.description}"+ ),+ input_parameters=entry.handle.input_schema,+ is_deprecated=False,+ name=entry.handle.name,+ no_auth=entry.handle.extends_toolkit is None,+ output_parameters=entry.handle.output_schema or {},+ scopes=[],+ slug=entry.final_slug,+ tags=[],+ toolkit=ItemToolkit(logo="", name=toolkit_name, slug=toolkit_slug),+ version="latest",+ )++ def _custom_toolkit_name(self, toolkit_slug: str) -> t.Optional[str]:+ if self._custom_tools_map is None:+ return None++ for toolkit in self._custom_tools_map.toolkits or []:+ if toolkit.slug.lower() == toolkit_slug.lower():+ return toolkit.name+ return None+def _create_routing_execute_fn(self,tools_model: t.Any,diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex 36fa8d0bd..2cefdc4db 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -3,7 +3,9 @@from unittest.mock import MagicMock, patchimport pytest+from pydantic import BaseModel, Field+from composio.core.models.custom_tool import ExperimentalAPIfrom composio.core.models.tool_router import (ToolkitConnectionsDetails,ToolkitConnectionState,@@ -16,6 +18,15 @@ from composio.core.models.tool_router import (ToolRouterToolkitsDisableConfig,ToolRouterToolkitsEnableConfig,)+from composio.core.models.tool_router_session import (+ DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX,+)++experimental_api = ExperimentalAPI()+++class GrepInput(BaseModel):+ pattern: str = Field(description="Pattern to search for")@pytest.fixture@@ -604,6 +615,63 @@ class TestToolRouter:assert kwargs["preload"] == {"tools": ["GMAIL_FETCH_EMAILS"]}assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]+ def test_create_session_with_preload_all(self, tool_router, mock_client):+ """preload tools='all' is forwarded and exposed on the session."""+ mock_client.tool_router.session.create.return_value.config.preload.tools = "all"++ session = tool_router.create(+ user_id="user_123",+ preload={"tools": "all"},+ )++ kwargs = mock_client.tool_router.session.create.call_args.kwargs+ assert kwargs["preload"] == {"tools": "all"}+ assert session.preload.tools == "all"++ def test_create_session_with_direct_tools_preset(self, tool_router, mock_client):+ """direct_tools applies SDK-side defaults for direct tool exposure."""+ mock_client.tool_router.session.create.return_value.config.preload.tools = "all"++ session = tool_router.create(+ user_id="user_123",+ session_preset="direct_tools",+ toolkits=["github"],+ )++ kwargs = mock_client.tool_router.session.create.call_args.kwargs+ assert kwargs["toolkits"] == {"enable": ["github"]}+ assert kwargs["manage_connections"] == {"enable": False}+ assert kwargs["workbench"] == {"enable": False}+ assert kwargs["preload"] == {"tools": "all"}+ assert kwargs["search"] == {"enable": False}+ assert kwargs["execute"] == {"enable_multi_execute": False}+ assert session.preload.tools == "all"++ def test_create_session_with_direct_tools_preset_overrides(+ self, tool_router, mock_client+ ):+ """Explicit user fields override direct_tools defaults."""+ mock_client.tool_router.session.create.return_value.config.preload.tools = [+ "GITHUB_CREATE_ISSUE"+ ]++ session = tool_router.create(+ user_id="user_123",+ session_preset="direct_tools",+ toolkits=["github"],+ manage_connections=True,+ workbench={"enable": True},+ preload={"tools": ["GITHUB_CREATE_ISSUE"]},+ )++ kwargs = mock_client.tool_router.session.create.call_args.kwargs+ assert kwargs["manage_connections"] == {"enable": True}+ assert kwargs["workbench"] == {"enable": True}+ assert kwargs["preload"] == {"tools": ["GITHUB_CREATE_ISSUE"]}+ assert kwargs["search"] == {"enable": False}+ assert kwargs["execute"] == {"enable_multi_execute": False}+ assert session.preload.tools == ["GITHUB_CREATE_ISSUE"]+def test_create_session_complex_config(self, tool_router, mock_client):"""Test creating a session with complex configuration."""session = tool_router.create(@@ -1073,6 +1141,60 @@ class TestToolRouter:assert [tool.slug for tool in wrapped_tools] == ["GMAIL_FETCH_EMAILS"]assert result == "mocked-wrapped-tools"+ @patch("composio.core.models.tools.Tools")+ def test_tools_function_includes_preloaded_custom_tools(+ self,+ mock_tools_class,+ tool_router,+ mock_client,+ mock_provider,+ ):+ """Custom tools preloaded by the create response are exposed locally."""++ @experimental_api.tool(+ slug="GREP",+ name="Grep",+ description="Search local text",+ )+ def grep(input: GrepInput, ctx):+ return {"matches": []}++ mock_response = mock_client.tool_router.session.create.return_value+ mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS", "server_grep"]+ mock_response.experimental = MagicMock()+ mock_response.experimental.assistive_prompt = None+ mock_response.experimental.custom_toolkits = []+ mock_custom_tool = MagicMock()+ mock_custom_tool.slug = "SERVER_GREP"+ mock_custom_tool.original_slug = "GREP"+ mock_custom_tool.extends_toolkit = None+ mock_response.experimental.custom_tools = [mock_custom_tool]++ mock_tools_instance = MagicMock()+ mock_tool = MagicMock()+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"+ mock_tool.toolkit.slug = "composio"+ mock_tool.input_parameters = {}+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}+ mock_tools_class.return_value = mock_tools_instance+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"++ session = tool_router.create(+ user_id="user_123",+ experimental={"custom_tools": [grep]},+ )+ result = session.tools()++ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]+ assert [tool.slug for tool in wrapped_tools] == [+ "COMPOSIO_SEARCH_TOOLS",+ "SERVER_GREP",+ ]+ assert DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX in wrapped_tools[1].description+ assert wrapped_tools[1].toolkit.slug == "custom"+ assert result == "mocked-custom-tools"+@patch("composio.core.models.tools.Tools")def test_tools_function_with_modifiers(self,diff --git a/ts/packages/core/src/lib/toolRouterParams.ts b/ts/packages/core/src/lib/toolRouterParams.tsindex e82fda173..97b57be66 100644--- a/ts/packages/core/src/lib/toolRouterParams.ts+++ b/ts/packages/core/src/lib/toolRouterParams.ts@@ -114,7 +114,7 @@ export const transformToolRouterManageConnectionsParams = (export const transformToolRouterWorkbenchParams = (params?: ToolRouterCreateSessionConfig['workbench']): SessionCreateParams.Workbench | undefined => {- if (!params) {+ if (params === undefined) {return undefined;}diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex 3b8d21852..58e602568 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -284,6 +284,7 @@ export function buildCustomToolsMap(const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {const originalSlug = handle.slug.toUpperCase();+ const finalSlugKey = finalSlug.toUpperCase();// Length validated early in createCustomTool/createCustomToolkit, but check as safety netif (finalSlug.length > MAX_SLUG_LENGTH) {@@ -294,7 +295,7 @@ export function buildCustomToolsMap(}// Check cross-group collisions on final slug- if (byFinalSlug.has(finalSlug)) {+ if (byFinalSlug.has(finalSlugKey)) {throw new ValidationError(`Custom tool slug collision: "${finalSlug}" is already registered.`);@@ -309,7 +310,7 @@ export function buildCustomToolsMap(}const entry: CustomToolsMapEntry = { handle, finalSlug, toolkit };- byFinalSlug.set(finalSlug, entry);+ byFinalSlug.set(finalSlugKey, entry);byOriginalSlug.set(originalSlug, entry);};@@ -415,7 +416,7 @@ export function buildCustomToolsMapFromResponse(finalSlug,toolkit: toolkit ?? match.toolkit,};- byFinalSlug.set(finalSlug, entry);+ byFinalSlug.set(finalSlug.toUpperCase(), entry);byOriginalSlug.set(originalSlug.toUpperCase(), entry);};@@ -437,3 +438,53 @@ export function buildCustomToolsMapFromResponse(return { byFinalSlug, byOriginalSlug, toolkits };}++/**+ * Find a custom tool entry by final slug only.+ *+ * @internal+ */+export function findCustomToolMapEntryByFinalSlug(+ customToolsMap: CustomToolsMap | undefined,+ slug: string+): CustomToolsMapEntry | undefined {+ return customToolsMap?.byFinalSlug.get(slug.toUpperCase());+}++/**+ * Resolve custom tools that the backend selected for direct preload.+ *+ * The backend is the source of truth for preload expansion, including "all".+ * The SDK only keeps the final custom slugs it can serve locally because+ * the session tools endpoint only returns backend-managed tool schemas.+ *+ * @internal+ */+export function getPreloadedCustomToolSlugs(+ toolRouterTools: readonly string[] | undefined,+ customToolsMap: CustomToolsMap | undefined+): string[] {+ if (!toolRouterTools?.length || !customToolsMap) {+ return [];+ }++ const seen = new Set<string>();+ const customToolSlugs: string[] = [];++ for (const slug of toolRouterTools) {+ const entry = findCustomToolMapEntryByFinalSlug(customToolsMap, slug);+ if (!entry) {+ continue;+ }++ const finalSlugKey = entry.finalSlug.toUpperCase();+ if (seen.has(finalSlugKey)) {+ continue;+ }++ seen.add(finalSlugKey);+ customToolSlugs.push(entry.finalSlug);+ }++ return customToolSlugs;+}diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.tsindex 0e3966a28..0cfe85f8e 100644--- a/ts/packages/core/src/models/ToolRouter.ts+++ b/ts/packages/core/src/models/ToolRouter.ts@@ -46,6 +46,7 @@ import {import { ToolRouterSession } from './ToolRouterSession';import {buildCustomToolsMapFromResponse,+ getPreloadedCustomToolSlugs,serializeCustomTools,serializeCustomToolkits,} from './CustomTool';@@ -109,6 +110,13 @@ export class ToolRouter<* customToolkits: [myToolkit],* },* });+ *+ * // Expose all tools allowed by filters directly, without meta/helper tools.+ * // `preload.tools = "all"` requires a positive filter such as `toolkits`.+ * const directSession = await composio.create('user_123', {+ * sessionPreset: 'direct_tools',+ * toolkits: ['github'],+ * });* ```*/async create(@@ -116,6 +124,7 @@ export class ToolRouter<config?: ToolRouterCreateSessionConfig): Promise<Session<TToolCollection, TTool, TProvider>> {const routerConfig = ToolRouterCreateSessionConfigSchema.parse(config ?? {});+ const isDirectToolsPreset = routerConfig.sessionPreset === 'direct_tools';// Extract custom tools/toolkits from experimental configconst customTools = routerConfig.experimental?.customTools;@@ -152,6 +161,10 @@ export class ToolRouter<workbench: transformToolRouterWorkbenchParams(routerConfig.workbench),multi_account: multiAccountPayload,preload: routerConfig.preload,+ ...(isDirectToolsPreset && {+ search: { enable: false },+ execute: { enable_multi_execute: false },+ }),experimental: Object.keys(experimentalPayload).length > 0 ? experimentalPayload : undefined,};@@ -167,6 +180,13 @@ export class ToolRouter<session.experimental);}+ const metadata = {+ ...getSessionMetadata(session),+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(+ session.tool_router_tools,+ customToolsMap+ ),+ };const assistivePrompt = session.experimental?.assistive_prompt;@@ -178,7 +198,7 @@ export class ToolRouter<{ assistivePrompt },customToolsMap,userId,- getSessionMetadata(session)+ metadata);}diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex c10e2375c..6231ff8f3 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -43,9 +43,12 @@ import type { SessionExecuteParams } from '@composio/client/resources/tool-routeimport { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';import { SessionContextImpl } from './SessionContext';import { findCustomTool, executeCustomTool } from './customToolExecution';+import { findCustomToolMapEntryByFinalSlug } from './CustomTool';import { transformProxyParams } from './proxyParamsTransform';const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';+export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =+ '[Direct tool - call directly, no search or connection check needed beforehand.]';export class ToolRouterSession<TToolCollection,@@ -58,6 +61,7 @@ export class ToolRouterSession<public readonly preload: ToolRouterSessionPreloadConfig;public readonly configVersion?: number;public readonly warnings: ToolRouterSessionWarning[];+ private readonly preloadedCustomToolSlugs: string[];/** Singleton session context — shared across all custom tool executions */private readonly sessionContext?: SessionContext;@@ -84,6 +88,7 @@ export class ToolRouterSession<this.preload = metadata?.preload ?? { tools: [] };this.configVersion = metadata?.configVersion;this.warnings = metadata?.warnings ?? [];+ this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];// Create singleton session context if custom tools are boundif (customToolsMap && userId) {@@ -106,7 +111,8 @@ export class ToolRouterSession<this.sessionId,modifiers?.modifySchema ? { modifySchema: modifiers.modifySchema } : undefined);- const toolBySlug = new Map(tools.map(tool => [tool.slug.toUpperCase(), tool]));+ const sessionTools = await this.addPreloadedCustomTools(tools, modifiers);+ const toolBySlug = new Map(sessionTools.map(tool => [tool.slug.toUpperCase(), tool]));if (this.hasCustomTools()) {// Create an execute function that splits local/remote tools in COMPOSIO_MULTI_EXECUTE_TOOL@@ -115,7 +121,7 @@ export class ToolRouterSession<input: Record<string, unknown>): Promise<ToolExecuteResponse> => {if (toolSlug === COMPOSIO_MULTI_EXECUTE_TOOL) {- return this.routeMultiExecute(input, ToolsModel, tools, modifiers);+ return this.routeMultiExecute(input, ToolsModel, sessionTools, modifiers);}return ToolsModel.executeSessionTool(toolSlug,@@ -131,16 +137,84 @@ export class ToolRouterSession<'Pass a provider in the Composio constructor.');}- return this.config.provider.wrapTools(tools, routingExecuteFn) as ReturnType<+ return this.config.provider.wrapTools(sessionTools, routingExecuteFn) as ReturnType<TProvider['wrapTools']>;}// Standard path (no local tools)- const wrappedTools = ToolsModel.wrapToolsForToolRouter(this.sessionId, tools, modifiers);+ const wrappedTools = ToolsModel.wrapToolsForToolRouter(this.sessionId, sessionTools, modifiers);return wrappedTools as ReturnType<TProvider['wrapTools']>;}+ private async addPreloadedCustomTools(+ tools: Tool[],+ modifiers?: SessionMetaToolOptions+ ): Promise<Tool[]> {+ const customTools = await this.getPreloadedCustomToolSchemas(modifiers);+ if (!customTools.length) {+ return tools;+ }++ const existingSlugs = new Set(tools.map(tool => tool.slug.toUpperCase()));+ const appendedTools = customTools.filter(tool => !existingSlugs.has(tool.slug.toUpperCase()));+ if (!appendedTools.length) {+ return tools;+ }++ return [...tools, ...appendedTools];+ }++ private async getPreloadedCustomToolSchemas(modifiers?: SessionMetaToolOptions): Promise<Tool[]> {+ if (!this.customToolsMap || !this.preloadedCustomToolSlugs.length) {+ return [];+ }++ const tools: Tool[] = [];+ for (const slug of this.preloadedCustomToolSlugs) {+ const entry = findCustomToolMapEntryByFinalSlug(this.customToolsMap, slug);+ if (!entry) {+ continue;+ }++ let tool = this.customToolEntryToTool(entry);+ if (modifiers?.modifySchema) {+ tool = await modifiers.modifySchema({+ toolSlug: tool.slug,+ toolkitSlug: tool.toolkit?.slug ?? 'custom',+ schema: tool,+ });+ }+ tools.push(tool);+ }+ return tools;+ }++ private customToolEntryToTool(entry: CustomToolsMapEntry): Tool {+ const toolkitSlug = entry.toolkit ?? 'custom';+ const customToolkit = this.customToolsMap?.toolkits?.find(+ toolkit => toolkit.slug.toLowerCase() === toolkitSlug.toLowerCase()+ );+ const toolkitName = customToolkit?.name ?? entry.toolkit ?? 'Custom';++ return {+ slug: entry.finalSlug,+ name: entry.handle.name,+ description: `${DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX}\n${entry.handle.description}`,+ inputParameters: entry.handle.inputSchema as Tool['inputParameters'],+ outputParameters: entry.handle.outputSchema as Tool['outputParameters'],+ tags: [],+ toolkit: {+ slug: toolkitSlug,+ name: toolkitName,+ },+ isDeprecated: false,+ availableVersions: [],+ scopes: [],+ isNoAuth: !entry.handle.extendsToolkit,+ };+ }+/*** List all custom tools registered in this session.* Returns tools with their final slugs, schemas, and resolved toolkit.diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.tsindex 80e140bfd..988294859 100644--- a/ts/packages/core/src/types/toolRouter.types.ts+++ b/ts/packages/core/src/types/toolRouter.types.ts@@ -169,8 +169,15 @@ export const ToolRouterConfigToolsSchema = z});export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;-export const ToolRouterCreateSessionConfigSchema = z+const ToolRouterCreateSessionConfigBaseSchema = z.object({+ sessionPreset: z+ .literal('direct_tools')+ .optional()+ .describe(+ 'Shortcut to expose every tool allowed by the session filters directly in session.tools() and the MCP tool list. This disables meta tools by default (search, multi-execute, manage-connections, and workbench). Use when all tools are known upfront and helper/meta tools are not needed. Without this preset, ToolRouter uses its default configuration with meta tools enabled.'+ ),+tools: z.record(z.string(), z.union([ToolRouterToolsParamSchema, ToolRouterConfigToolsSchema])).optional()@@ -225,7 +232,7 @@ export const ToolRouterCreateSessionConfigSchema = z'The auto offload threshold in characters for the tool execution to be moved into workbench'),sandboxSize: SandboxSizeSchema.optional().describe(- 'Sandbox compute tier for the workbench. One of "standard" (1 vCPU / 1 GB), "medium" (2 vCPU / 2 GB), "large" (4 vCPU / 4 GB), or "xlarge" (8 vCPU / 8 GB). Defaults to "standard" server-side. Changing this on an existing session recreates the sandbox on next access; the session\'s in-memory FS is lost, but /mnt/files/ persists.'+ 'Sandbox compute tier for the workbench. One of "standard" (1 vCPU / 1 GB), "medium" (2 vCPU / 2 GB), "large" (4 vCPU / 4 GB), or "xlarge" (8 vCPU / 8 GB). Defaults to "standard" server-side. Changing this on an existing session recreates the session\'s workbench sandbox on next access; the in-memory FS is lost, but /mnt/files/ persists.'),}).optional()@@ -258,10 +265,10 @@ export const ToolRouterCreateSessionConfigSchema = zpreload: z.object({tools: z- .array(z.string())+ .union([z.array(z.string()), z.literal('all')]).optional().describe(- 'Tool slugs to preload into session.tools() and the MCP tool list. The backend validates slugs against the session filters.'+ 'Tool slugs to preload into session.tools() and the MCP tool list, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.'),}).strict()@@ -299,9 +306,32 @@ export const ToolRouterCreateSessionConfigSchema = z}).partial().describe('The config for the tool router session');++const applyDirectToolsPresetDefaults = (value: unknown): unknown => {+ if (!value || typeof value !== 'object' || Array.isArray(value)) {+ return value;+ }++ const config = value as Record<string, unknown>;+ if (config.sessionPreset !== 'direct_tools') {+ return value;+ }++ return {+ ...config,+ manageConnections: config.manageConnections === undefined ? false : config.manageConnections,+ workbench: config.workbench === undefined ? { enable: false } : config.workbench,+ preload: config.preload === undefined ? { tools: 'all' } : config.preload,+ };+};++export const ToolRouterCreateSessionConfigSchema = z+ .preprocess(applyDirectToolsPresetDefaults, ToolRouterCreateSessionConfigBaseSchema)+ .describe('The config for the tool router session');/*** The config for the tool router session.*+ * @param {'direct_tools'} [sessionPreset] - Shortcut that exposes every tool allowed by the session filters directly in session.tools() and the MCP tool list. Disables search, multi-execute, manage-connections, and workbench by default; explicit overrides for supported fields still win. Without this preset, ToolRouter uses the default configuration with meta tools enabled.* @param {ToolRouterToolkitsParamSchema | ToolRouterToolkitsDisabledConfigSchema | ToolRouterToolkitsEnabledConfigSchema} toolkits - The toolkits to use in the tool router session* @param {Record<string, ToolRouterToolsParam | ToolRouterConfigTools>} tools - The tools to configure per toolkit (key is toolkit slug)* @param {Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>} tags - Global tags to filter tools by behavior@@ -320,7 +350,7 @@ export const ToolRouterCreateSessionConfigSchema = z* @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)* @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected* @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list- * @param {string[]} [preload.tools] - Tool slugs to preload. Server-side validation ensures they exist and are allowed by the session filters.+ * @param {string[] | 'all'} [preload.tools] - Tool slugs to preload, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.*/export type ToolRouterCreateSessionConfig = z.infer<typeof ToolRouterCreateSessionConfigSchema>;@@ -544,6 +574,7 @@ export interface ToolRouterSessionMetadata {preload?: ToolRouterSessionPreloadConfig;configVersion?: number;warnings?: ToolRouterSessionWarning[];+ preloadedCustomToolSlugs?: string[];}export const SessionProxyExecuteParamsSchema = z.object({diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.tsindex 7d55e0a44..3569291e1 100644--- a/ts/packages/core/test/models/toolRouter.test.ts+++ b/ts/packages/core/test/models/toolRouter.test.ts@@ -1,4 +1,5 @@import { describe, it, expect, vi, beforeEach } from 'vitest';+import { z } from 'zod/v3';import { ToolRouter } from '../../src/models/ToolRouter';import ComposioClient from '@composio/client';import { telemetry } from '../../src/telemetry/Telemetry';@@ -6,6 +7,8 @@ import { MockProvider } from '../utils/mocks/provider.mock';import { Tools } from '../../src/models/Tools';import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';import { ToolRouterCreateSessionConfig, Session } from '../../src/types/toolRouter.types';+import { createCustomTool } from '../../src/models/CustomTool';+import { DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX } from '../../src/models/ToolRouterSession';// Mock dependenciesvi.mock('../../src/telemetry/Telemetry', () => ({@@ -262,6 +265,106 @@ describe('ToolRouter', () => {expect(session.configVersion).toBe(2);});+ it('should create a session with preload all', async () => {+ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ config: {+ preload: { tools: 'all' },+ },+ config_version: 2,+ });++ const session = await toolRouter.create(userId, {+ toolkits: ['github'],+ preload: { tools: 'all' },+ });++ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({+ user_id: userId,+ toolkits: {+ enable: ['github'],+ },+ auth_configs: undefined,+ connected_accounts: undefined,+ tools: undefined,+ tags: undefined,+ manage_connections: createExpectedManageConnections(),+ workbench: undefined,+ preload: { tools: 'all' },+ });++ expect(session.preload.tools).toBe('all');+ });++ it('should apply the direct_tools session preset defaults', async () => {+ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ config: {+ preload: { tools: 'all' },+ },+ });++ const session = await toolRouter.create(userId, {+ sessionPreset: 'direct_tools',+ toolkits: ['github'],+ });++ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({+ user_id: userId,+ toolkits: {+ enable: ['github'],+ },+ auth_configs: undefined,+ connected_accounts: undefined,+ tools: undefined,+ tags: undefined,+ manage_connections: { enable: false },+ workbench: { enable: false },+ multi_account: undefined,+ preload: { tools: 'all' },+ search: { enable: false },+ execute: { enable_multi_execute: false },+ experimental: undefined,+ });+ expect(session.preload.tools).toBe('all');+ });++ it('should respect explicit overrides with the direct_tools session preset', async () => {+ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ config: {+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },+ },+ });++ const session = await toolRouter.create(userId, {+ sessionPreset: 'direct_tools',+ toolkits: ['github'],+ manageConnections: true,+ workbench: { enable: true },+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },+ });++ expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({+ user_id: userId,+ toolkits: {+ enable: ['github'],+ },+ auth_configs: undefined,+ connected_accounts: undefined,+ tools: undefined,+ tags: undefined,+ manage_connections: { enable: true },+ workbench: { enable: true },+ multi_account: undefined,+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },+ search: { enable: false },+ execute: { enable_multi_execute: false },+ experimental: undefined,+ });+ expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);+ });+it('should create a session with user ID only and verify MCP type transformation', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);@@ -2240,6 +2343,83 @@ describe('ToolRouter', () => {expect(tools).toBe('mocked-wrapped-tools');});+ it('should include preloaded custom tools selected by the create response', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ inputParams: z.object({+ pattern: z.string().describe('Pattern to search for'),+ }),+ execute: vi.fn(async () => ({ matches: [] })),+ });++ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'server_grep'],+ experimental: {+ custom_tools: [+ {+ slug: 'SERVER_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');++ const session = await toolRouter.create(userId, {+ experimental: { customTools: [grepTool] },+ });+ const tools = await session.tools();++ expect(mockProvider.wrapTools).toHaveBeenCalledTimes(1);+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{+ slug: string;+ description?: string;+ toolkit?: { slug: string; name: string };+ }>;+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'SERVER_GREP']);+ expect(wrappedTools[1].description).toContain(DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX);+ expect(wrappedTools[1].toolkit).toEqual({ slug: 'custom', name: 'Custom' });+ expect(tools).toBe('mocked-custom-tools');+ });++ it('should not expose custom tools unless the backend preloaded them', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ inputParams: z.object({+ pattern: z.string(),+ }),+ execute: vi.fn(async () => ({ matches: [] })),+ });++ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],+ experimental: {+ custom_tools: [+ {+ slug: 'LOCAL_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');++ const session = await toolRouter.create(userId, {+ preload: { tools: 'all' },+ experimental: { customTools: [grepTool] },+ });+ await session.tools();++ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);+ });+it('should handle tools fetching errors', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);