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 SDK-local custom tool preload
Dhawal Upadhyay847a8a04a636
diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex b4664ec56..6a77bf74e 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -156,6 +156,7 @@ def _create_tool(execute: CustomToolExecuteFn,extends_toolkit: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,) -> CustomTool:"""Internal: create and validate a CustomTool."""context = "experimental.tool"@@ -218,6 +219,7 @@ def _create_tool(output_schema=output_schema,input_params=input_params,execute=execute,+ preload=preload,)@@ -258,6 +260,7 @@ def _infer_tool_from_function(description: t.Optional[str] = None,extends_toolkit: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,annotation_locals: t.Optional[t.Mapping[str, t.Any]] = None,) -> CustomTool:"""Create a CustomTool by inferring metadata from a decorated function.@@ -341,6 +344,7 @@ def _infer_tool_from_function(execute=execute,extends_toolkit=extends_toolkit,output_params=output_params,+ preload=preload,)@@ -372,7 +376,14 @@ class ExperimentalToolkit:return {"results": []}"""- def __init__(self, *, slug: str, name: str, description: str) -> None:+ def __init__(+ self,+ *,+ slug: str,+ name: str,+ description: str,+ preload: t.Optional[bool] = None,+ ) -> None:context = "experimental.Toolkit"_validate_slug(slug, context)if not name:@@ -383,6 +394,7 @@ class ExperimentalToolkit:self.slug = slugself.name = nameself.description = description+ self.preload = preloadself._tools: t.List[CustomTool] = []@property@@ -400,6 +412,7 @@ class ExperimentalToolkit:name: t.Optional[str] = None,description: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...def tool(@@ -410,6 +423,7 @@ class ExperimentalToolkit:name: t.Optional[str] = None,description: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:"""Decorator to add a tool to this toolkit.@@ -425,6 +439,7 @@ class ExperimentalToolkit:name=name,description=description,output_params=output_params,+ preload=preload,annotation_locals=annotation_locals,# No extends_toolkit for toolkit tools)@@ -441,6 +456,7 @@ class ExperimentalToolkit:name=name,description=description,output_params=output_params,+ preload=preload,annotation_locals=_get_caller_locals(),)_validate_slug_length(@@ -479,6 +495,7 @@ class ExperimentalAPI:description: t.Optional[str] = None,extends_toolkit: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...def tool(@@ -490,6 +507,7 @@ class ExperimentalAPI:description: t.Optional[str] = None,extends_toolkit: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,+ preload: t.Optional[bool] = None,) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:"""Decorator to create a custom tool from a function.@@ -526,6 +544,7 @@ class ExperimentalAPI:description=description,extends_toolkit=extends_toolkit,output_params=output_params,+ preload=preload,annotation_locals=annotation_locals,)@@ -537,6 +556,7 @@ class ExperimentalAPI:description=description,extends_toolkit=extends_toolkit,output_params=output_params,+ preload=preload,annotation_locals=_get_caller_locals(),)return decorator@@ -547,7 +567,28 @@ class ExperimentalAPI:# ────────────────────────────────────────────────────────────────-def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.Any]]:+def _serialized_preload_value(+ preload: t.Optional[bool],+ inherited_preload: t.Optional[bool],+ default_preload: bool,+) -> t.Optional[bool]:+ resolved = (+ preload+ if preload is not None+ else inherited_preload+ if inherited_preload is not None+ else default_preload+ )+ if preload is not None or inherited_preload is not None or default_preload:+ return resolved+ return None+++def serialize_custom_tools(+ tools: t.List[CustomTool],+ *,+ default_preload: bool = False,+) -> t.List[t.Dict[str, t.Any]]:"""Serialize custom tools into the format expected by the backend."""result = []for tool in tools:@@ -561,12 +602,19 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.Anentry["output_schema"] = tool.output_schemaif tool.extends_toolkit:entry["extends_toolkit"] = tool.extends_toolkit+ preload = _serialized_preload_value(+ tool.preload, inherited_preload=None, default_preload=default_preload+ )+ if preload is not None:+ entry["preload"] = preloadresult.append(entry)return resultdef serialize_custom_toolkits(toolkits: t.Sequence[ExperimentalToolkit],+ *,+ default_preload: bool = False,) -> t.List[t.Dict[str, t.Any]]:"""Serialize custom toolkits into the format expected by the backend."""result = []@@ -581,15 +629,26 @@ def serialize_custom_toolkits(}if tool.output_schema:entry["output_schema"] = tool.output_schema+ preload = _serialized_preload_value(+ tool.preload,+ inherited_preload=tk.preload,+ default_preload=default_preload,+ )+ if preload is not None:+ entry["preload"] = preloadtoolkit_tools.append(entry)- result.append(- {- "slug": tk.slug,- "name": tk.name,- "description": tk.description,- "tools": toolkit_tools,- }+ toolkit_entry: t.Dict[str, t.Any] = {+ "slug": tk.slug,+ "name": tk.name,+ "description": tk.description,+ "tools": toolkit_tools,+ }+ preload = _serialized_preload_value(+ tk.preload, inherited_preload=None, default_preload=default_preload)+ if preload is not None:+ toolkit_entry["preload"] = preload+ result.append(toolkit_entry)return result@@ -729,23 +788,63 @@ def find_custom_tool_map_entry_by_final_slug(return custom_tools_map.by_final_slug.get(slug.upper())+def assert_no_custom_tool_slugs_in_preload(+ preload_tools: t.Union[t.Sequence[str], t.Literal["all"], None],+ custom_tools_map: t.Optional[CustomToolsMap],+) -> None:+ """Reject legacy top-level preload of custom tool slugs."""+ if preload_tools is None or preload_tools == "all":+ return++ custom_preload_slugs = []+ for slug in preload_tools:+ normalized = slug.upper()+ if normalized.startswith(LOCAL_TOOL_PREFIX) or (+ custom_tools_map is not None+ and (+ normalized in custom_tools_map.by_original_slug+ or normalized in custom_tools_map.by_final_slug+ )+ ):+ custom_preload_slugs.append(slug)++ if custom_preload_slugs:+ raise ValidationError(+ "Custom tool slugs are not supported in preload.tools: "+ f"{', '.join(custom_preload_slugs)}. Set preload=True on the SDK "+ "custom tool or custom toolkit definition instead."+ )++def get_preloaded_custom_tool_slugs(- tool_router_tools: t.Optional[t.Iterable[str]],custom_tools_map: t.Optional[CustomToolsMap],+ *,+ default_preload: bool = False,) -> 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 final custom tool slugs selected locally for preload."""+ if 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),+ for entry in custom_tools_map.by_final_slug.values():+ toolkit = next(+ (+ tk+ for tk in custom_tools_map.toolkits or []+ if entry.toolkit and tk.slug.lower() == entry.toolkit.lower()+ ),+ None,+ )+ should_preload = (+ entry.handle.preload+ if entry.handle.preload is not None+ else toolkit.preload+ if toolkit is not None and toolkit.preload is not None+ else default_preload)- if entry is None:+ if not should_preload:continuefinal_slug_key = entry.final_slug.upper()diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.pyindex 4fae37115..03247cc00 100644--- a/python/composio/core/models/custom_tool_types.py+++ b/python/composio/core/models/custom_tool_types.py@@ -106,6 +106,7 @@ class CustomTool:execute: CustomToolExecuteFnextends_toolkit: t.Optional[str] = Noneoutput_schema: t.Optional[t.Dict[str, t.Any]] = None+ preload: t.Optional[bool] = None# ────────────────────────────────────────────────────────────────diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex d8392d4e6..6817d9c85 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -19,6 +19,8 @@ from composio.client import HttpClientfrom composio.core.models.base import Resourcefrom composio.core.models.custom_tool import (ExperimentalToolkit,+ assert_no_custom_tool_slugs_in_preload,+ build_custom_tools_map,build_custom_tools_map_from_response,get_preloaded_custom_tool_slugs,serialize_custom_tools,@@ -627,6 +629,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):- 'assistive_prompt' (dict): Configuration for assistive prompt generation.- 'user_timezone' (str): IANA timezone identifier(e.g., "America/New_York", "Europe/London").+ - 'custom_tools' / 'custom_toolkits': SDK custom tools.+ Set preload=True on a custom tool or toolkit to expose+ it directly from session.tools(); otherwise custom tools+ remain search-only.Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}:return: Tool router session object@@ -716,6 +722,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):workbench=workbench,preload=preload,)+ default_custom_preload = preload is not None and preload.get("tools") == "all"# Parse manage_connections configmanage_connections = (@@ -851,6 +858,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):# experimental.assistive_prompt_config.user_timezonecustom_tools: t.Optional[t.List[CustomTool]] = Nonecustom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None+ local_custom_tools_map: t.Optional[CustomToolsMap] = None+ inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = Noneif experimental is not None:experimental_payload: t.Dict[str, t.Any] = {}@@ -866,16 +875,36 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):# Serialize custom tools and toolkits for the backendcustom_tools = experimental.get("custom_tools")custom_toolkits = experimental.get("custom_toolkits")+ if custom_tools or custom_toolkits:+ local_custom_tools_map = build_custom_tools_map(+ custom_tools or [],+ custom_toolkits,+ )+ assert_no_custom_tool_slugs_in_preload(+ preload.get("tools") if preload is not None else None,+ local_custom_tools_map,+ )if custom_tools:experimental_payload["custom_tools"] = serialize_custom_tools(- custom_tools+ custom_tools,+ default_preload=default_custom_preload,)if custom_toolkits:experimental_payload["custom_toolkits"] = serialize_custom_toolkits(- custom_toolkits+ custom_toolkits,+ default_preload=default_custom_preload,)+ if (+ "custom_tools" in experimental_payload+ or "custom_toolkits" in experimental_payload+ ):+ inline_custom_tools_payload = {+ "custom_tools": experimental_payload.get("custom_tools"),+ "custom_toolkits": experimental_payload.get("custom_toolkits"),+ }+if experimental_payload:create_params["experimental"] = experimental_payload@@ -897,8 +926,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):experimental=session.experimental,)preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(- getattr(session, "tool_router_tools", None),custom_tools_map,+ default_preload=default_custom_preload,)# Transform experimental response:@@ -930,6 +959,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):user_id=user_id,preload=_session_preload_config(session),preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,+ inline_custom_tools_payload=inline_custom_tools_payload,)def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex 33b86603b..3306afc7d 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -105,6 +105,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):user_id: t.Optional[str] = None,preload: t.Optional[ToolRouterSessionPreloadConfig] = None,preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,+ inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None,) -> None:self._client = clientself._provider = provider@@ -119,6 +120,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):self._custom_tools_map = custom_tools_mapself._user_id = user_idself._preloaded_custom_tool_slugs = preloaded_custom_tool_slugs or []+ self._inline_custom_tools_payload = inline_custom_tools_payload# Create singleton session context if custom tools are boundself._session_context: t.Optional[SessionContextImpl] = None@@ -634,11 +636,14 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):Returns relevant tools for the given query with schemas and guidance."""- return self._client.tool_router.session.search(- session_id=self.session_id,- queries=[{"use_case": query}],- model=model if model else omit,- )+ params: t.Dict[str, t.Any] = {+ "session_id": self.session_id,+ "queries": [{"use_case": query}],+ "model": model if model else omit,+ }+ if self._inline_custom_tools_payload is not None:+ params["experimental"] = self._inline_custom_tools_payload+ return self._client.tool_router.session.search(**params)def execute(self,@@ -676,12 +681,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):)# Remote execution- return self._client.tool_router.session.execute(- session_id=self.session_id,- tool_slug=tool_slug,- arguments=arguments if arguments is not None else omit,- account=account if account is not None else omit,- )+ params: t.Dict[str, t.Any] = {+ "session_id": self.session_id,+ "tool_slug": tool_slug,+ "arguments": arguments if arguments is not None else omit,+ "account": account if account is not None else omit,+ }+ if self._inline_custom_tools_payload is not None:+ params["experimental"] = self._inline_custom_tools_payload+ return self._client.tool_router.session.execute(**params)def custom_tools(self, *, toolkit: t.Optional[str] = Nonediff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.pyindex 31170586b..9fb79bebf 100644--- a/python/tests/test_custom_tools.py+++ b/python/tests/test_custom_tools.py@@ -12,6 +12,7 @@ Covers:- Multi-execute routing (all-local, all-remote, mixed, parallel)"""+from dataclasses import replacefrom unittest.mock import MagicMockimport pytest@@ -145,6 +146,14 @@ class TestDecoratorTool:assert fetch_mail.extends_toolkit == "gmail"+ def test_decorator_with_preload(self):+ @exp.tool(preload=True)+ def fetch_context(input: GrepInput, ctx):+ """Fetch context."""+ return {}++ assert fetch_context.preload is True+def test_decorator_explicit_overrides(self):@exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")def whatever(input: GrepInput, ctx):@@ -408,12 +417,23 @@ class TestSerialization:result = serialize_custom_tools([email_tool])assert result[0]["extends_toolkit"] == "gmail"+ def test_serialize_custom_tool_preload_hint(self, grep_tool):+ preloaded = replace(grep_tool, preload=True)+ result = serialize_custom_tools([preloaded])+ assert result[0]["preload"] is True+def test_serialize_toolkit(self, role_toolkit):result = serialize_custom_toolkits([role_toolkit])assert len(result) == 1assert result[0]["slug"] == "ROLE_MANAGER"assert len(result[0]["tools"]) == 1+ def test_serialize_toolkit_preload_hint(self, role_toolkit):+ role_toolkit.preload = True+ result = serialize_custom_toolkits([role_toolkit])+ assert result[0]["preload"] is True+ assert result[0]["tools"][0]["preload"] is True+# ────────────────────────────────────────────────────────────────# Routing map testsdiff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex 2cefdc4db..ea86ba520 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, patchimport pytestfrom pydantic import BaseModel, Field+from composio.exceptions import ValidationErrorfrom composio.core.models.custom_tool import ExperimentalAPIfrom composio.core.models.tool_router import (ToolkitConnectionsDetails,@@ -628,6 +629,29 @@ class TestToolRouter:assert kwargs["preload"] == {"tools": "all"}assert session.preload.tools == "all"+ def test_create_session_rejects_custom_slug_in_top_level_preload(+ self, tool_router, mock_client+ ):+ @experimental_api.tool(+ slug="GREP",+ name="Grep",+ description="Search local text",+ )+ def grep(input: GrepInput, ctx):+ return {"matches": []}++ with pytest.raises(+ ValidationError,+ match="Set preload=True on the SDK custom tool",+ ):+ tool_router.create(+ user_id="user_123",+ preload={"tools": ["GREP"]},+ experimental={"custom_tools": [grep]},+ )++ mock_client.tool_router.session.create.assert_not_called()+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"@@ -672,6 +696,42 @@ class TestToolRouter:assert kwargs["execute"] == {"enable_multi_execute": False}assert session.preload.tools == ["GITHUB_CREATE_ISSUE"]+ def test_direct_tools_does_not_default_custom_preload_when_preload_overridden(+ self, tool_router, mock_client+ ):+ """Explicit preload config also overrides the custom-tool preload default."""++ @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.config.preload.tools = ["GITHUB_CREATE_ISSUE"]+ 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]++ tool_router.create(+ user_id="user_123",+ session_preset="direct_tools",+ toolkits=["github"],+ preload={"tools": ["GITHUB_CREATE_ISSUE"]},+ experimental={"custom_tools": [grep]},+ )++ kwargs = mock_client.tool_router.session.create.call_args.kwargs+ assert kwargs["preload"] == {"tools": ["GITHUB_CREATE_ISSUE"]}+ assert "preload" not in kwargs["experimental"]["custom_tools"][0]+def test_create_session_complex_config(self, tool_router, mock_client):"""Test creating a session with complex configuration."""session = tool_router.create(@@ -1149,18 +1209,19 @@ class TestToolRouter:mock_client,mock_provider,):- """Custom tools preloaded by the create response are exposed locally."""+ """Custom tools with SDK preload enabled are exposed locally."""@experimental_api.tool(slug="GREP",name="Grep",description="Search local text",+ preload=True,)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.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]mock_response.experimental = MagicMock()mock_response.experimental.assistive_prompt = Nonemock_response.experimental.custom_toolkits = []diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex 58e602568..efb4d8180 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -32,8 +32,8 @@ import {type CustomToolExecuteFn,type CustomToolsMap,type CustomToolsMapEntry,- type CustomToolDefinition,- type CustomToolkitDefinition,+ type CustomToolWireDefinition,+ type CustomToolkitWireDefinition,type InputParamsSchema,} from '../types/customTool.types';import type { SessionCreateResponse } from '@composio/client/resources/tool-router/session/session.mjs';@@ -184,6 +184,7 @@ export function createCustomTool<T extends z.ZodType>(name: validated.name,description: validated.description,extendsToolkit: validated.extendsToolkit,+ preload: validated.preload,inputSchema,outputSchema,inputParams,@@ -250,6 +251,7 @@ export function createCustomToolkit(slug: slugResult.data,name: validated.name,description: validated.description,+ preload: validated.preload,tools: options.tools,};}@@ -340,7 +342,36 @@ export function buildCustomToolsMap(* @param tools - The custom tools to serialize* @returns Array of CustomToolDefinition for the API payload*/-export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[] {+type CustomToolSerializationOptions = {+ defaultPreload?: boolean;+};++function shouldSerializePreload(+ preload: boolean | undefined,+ inheritedPreload: boolean | undefined,+ defaultPreload: boolean+): boolean | undefined {+ const resolved = preload ?? inheritedPreload ?? defaultPreload;+ if (preload !== undefined || inheritedPreload !== undefined || defaultPreload) {+ return resolved;+ }+ return undefined;+}++function preloadWireProperty(+ preload: boolean | undefined,+ inheritedPreload: boolean | undefined,+ defaultPreload: boolean+): { preload?: boolean } {+ const serializedPreload = shouldSerializePreload(preload, inheritedPreload, defaultPreload);+ return serializedPreload === undefined ? {} : { preload: serializedPreload };+}++export function serializeCustomTools(+ tools: CustomTool[],+ options: CustomToolSerializationOptions = {}+): CustomToolWireDefinition[] {+ const defaultPreload = options.defaultPreload ?? false;return tools.map(handle => ({slug: handle.slug,name: handle.name,@@ -348,6 +379,7 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[input_schema: handle.inputSchema,...(handle.outputSchema ? { output_schema: handle.outputSchema } : {}),...(handle.extendsToolkit ? { extends_toolkit: handle.extendsToolkit } : {}),+ ...preloadWireProperty(handle.preload, undefined, defaultPreload),}));}@@ -358,17 +390,23 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[* @param toolkits - The custom toolkits to serialize* @returns Array of CustomToolkitDefinition for the API payload*/-export function serializeCustomToolkits(toolkits: CustomToolkit[]): CustomToolkitDefinition[] {+export function serializeCustomToolkits(+ toolkits: CustomToolkit[],+ options: CustomToolSerializationOptions = {}+): CustomToolkitWireDefinition[] {+ const defaultPreload = options.defaultPreload ?? false;return toolkits.map(tk => ({slug: tk.slug,name: tk.name,description: tk.description,+ ...preloadWireProperty(tk.preload, undefined, defaultPreload),tools: tk.tools.map(t => ({slug: t.slug,name: t.name,description: t.description,input_schema: t.inputSchema,...(t.outputSchema ? { output_schema: t.outputSchema } : {}),+ ...preloadWireProperty(t.preload, tk.preload, defaultPreload),})),}));}@@ -452,28 +490,62 @@ export function findCustomToolMapEntryByFinalSlug(}/**- * Resolve custom tools that the backend selected for direct preload.+ * Reject legacy attempts to preload custom tools through top-level preload.tools.*- * 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.+ * Custom tool direct exposure is controlled by CustomTool.preload /+ * CustomToolkit.preload so it follows the current SDK-provided custom+ * definitions instead of stale session config.** @internal*/-export function getPreloadedCustomToolSlugs(- toolRouterTools: readonly string[] | undefined,+export function assertNoCustomToolSlugsInPreload(+ preloadTools: readonly string[] | 'all' | undefined,customToolsMap: CustomToolsMap | undefined+): void {+ if (!preloadTools || preloadTools === 'all') {+ return;+ }++ const customPreloadSlugs = preloadTools.filter(slug => {+ const normalized = slug.toUpperCase();+ return (+ normalized.startsWith(LOCAL_TOOL_PREFIX) ||+ customToolsMap?.byOriginalSlug.has(normalized) ||+ customToolsMap?.byFinalSlug.has(normalized)+ );+ });++ if (customPreloadSlugs.length) {+ throw new ValidationError(+ `Custom tool slugs are not supported in preload.tools: ${customPreloadSlugs.join(+ ', '+ )}. Set preload: true on the SDK custom tool or custom toolkit definition instead.`+ );+ }+}++/**+ * Resolve custom tools that the SDK should expose directly from session.tools().+ *+ * @internal+ */+export function getPreloadedCustomToolSlugs(+ customToolsMap: CustomToolsMap | undefined,+ defaultPreload = false): string[] {- if (!toolRouterTools?.length || !customToolsMap) {+ if (!customToolsMap) {return [];}const seen = new Set<string>();const customToolSlugs: string[] = [];- for (const slug of toolRouterTools) {- const entry = findCustomToolMapEntryByFinalSlug(customToolsMap, slug);- if (!entry) {+ for (const entry of customToolsMap.byFinalSlug.values()) {+ const toolkit = customToolsMap.toolkits?.find(+ tk => entry.toolkit && tk.slug.toLowerCase() === entry.toolkit.toLowerCase()+ );+ const shouldPreload = entry.handle.preload ?? toolkit?.preload ?? defaultPreload;+ if (!shouldPreload) {continue;}diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.tsindex 0cfe85f8e..58f14b8b1 100644--- a/ts/packages/core/src/models/ToolRouter.ts+++ b/ts/packages/core/src/models/ToolRouter.ts@@ -45,6 +45,8 @@ import {} from '../lib/toolRouterParams';import { ToolRouterSession } from './ToolRouterSession';import {+ assertNoCustomToolSlugsInPreload,+ buildCustomToolsMap,buildCustomToolsMapFromResponse,getPreloadedCustomToolSlugs,serializeCustomTools,@@ -111,6 +113,9 @@ export class ToolRouter<* },* });*+ * // Custom tools are searched by default. Set `preload: true` on a custom+ * // tool or toolkit to expose it directly from `session.tools()`.+ ** // 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', {@@ -129,6 +134,12 @@ export class ToolRouter<// Extract custom tools/toolkits from experimental configconst customTools = routerConfig.experimental?.customTools;const customToolkits = routerConfig.experimental?.customToolkits;+ const defaultCustomPreload = routerConfig.preload?.tools === 'all';+ const localCustomToolsMap =+ customTools?.length || customToolkits?.length+ ? buildCustomToolsMap(customTools ?? [], customToolkits)+ : undefined;+ assertNoCustomToolSlugsInPreload(routerConfig.preload?.tools, localCustomToolsMap);// Build the typed experimental payload for the backendconst experimentalPayload: SessionCreateParams['experimental'] = {};@@ -140,11 +151,22 @@ export class ToolRouter<}if (customTools?.length) {- experimentalPayload.custom_tools = serializeCustomTools(customTools);+ experimentalPayload.custom_tools = serializeCustomTools(customTools, {+ defaultPreload: defaultCustomPreload,+ });}if (customToolkits?.length) {- experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);+ experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits, {+ defaultPreload: defaultCustomPreload,+ });}+ const inlineCustomToolsPayload =+ experimentalPayload.custom_tools || experimentalPayload.custom_toolkits+ ? {+ custom_tools: experimentalPayload.custom_tools,+ custom_toolkits: experimentalPayload.custom_toolkits,+ }+ : undefined;const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);@@ -182,10 +204,8 @@ export class ToolRouter<}const metadata = {...getSessionMetadata(session),- preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(- session.tool_router_tools,- customToolsMap- ),+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),+ inlineCustomToolsPayload,};const assistivePrompt = session.experimental?.assistive_prompt;diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex 6231ff8f3..61f1d21f4 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -39,7 +39,10 @@ import type {} from '../types/customTool.types';import type { Tool, ToolExecuteResponse } from '../types/tool.types';import type { SessionProxyExecuteParams } from '../types/toolRouter.types';-import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';+import type {+ SessionExecuteParams,+ SessionSearchParams,+} from '@composio/client/resources/tool-router/session/session.mjs';import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';import { SessionContextImpl } from './SessionContext';import { findCustomTool, executeCustomTool } from './customToolExecution';@@ -62,6 +65,7 @@ export class ToolRouterSession<public readonly configVersion?: number;public readonly warnings: ToolRouterSessionWarning[];private readonly preloadedCustomToolSlugs: string[];+ private readonly inlineCustomToolsPayload: ToolRouterSessionMetadata['inlineCustomToolsPayload'];/** Singleton session context — shared across all custom tool executions */private readonly sessionContext?: SessionContext;@@ -89,6 +93,7 @@ export class ToolRouterSession<this.configVersion = metadata?.configVersion;this.warnings = metadata?.warnings ?? [];this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];+ this.inlineCustomToolsPayload = metadata?.inlineCustomToolsPayload;// Create singleton session context if custom tools are boundif (customToolsMap && userId) {@@ -354,10 +359,12 @@ export class ToolRouterSession<query: string;toolkits?: string[];}): Promise<ToolRouterSessionSearchResponse> {- const response = await this.client.toolRouter.session.search(this.sessionId, {+ const searchParams: SessionSearchParams & { toolkits?: string[] } = {queries: [{ use_case: params.query }],...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),- });+ ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),+ };+ const response = await this.client.toolRouter.session.search(this.sessionId, searchParams);const transformed = transformSearchResponse(response);return ToolRouterSessionSearchResponseSchema.parse(transformed);}@@ -395,6 +402,7 @@ export class ToolRouterSession<const executeParams: SessionExecuteParams = {tool_slug: toolSlug,arguments: arguments_ ?? {},+ ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),};if (options?.account) {executeParams.account = options.account;diff --git a/ts/packages/core/src/types/customTool.types.ts b/ts/packages/core/src/types/customTool.types.tsindex e077af92c..2d72b04e4 100644--- a/ts/packages/core/src/types/customTool.types.ts+++ b/ts/packages/core/src/types/customTool.types.ts@@ -135,6 +135,12 @@ export const CreateCustomToolBaseSchema = z.object({* Leave empty for tools that don't need any Composio-managed authentication.*/extendsToolkit: z.string().optional(),+ preload: z+ .boolean()+ .optional()+ .describe(+ 'When true, expose this custom tool directly from session.tools(). This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.'+ ),});/** Options for creating a custom tool via `createCustomTool()`. */@@ -163,6 +169,11 @@ export interface CustomTool {* Undefined means the tool doesn't need any Composio-managed authentication.*/readonly extendsToolkit?: string;+ /**+ * Whether this custom tool should be exposed directly from session.tools().+ * This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.+ */+ readonly preload?: boolean;readonly inputSchema: Record<string, unknown>;/** JSON Schema representation of the output (for backend documentation) */readonly outputSchema?: Record<string, unknown>;@@ -175,6 +186,10 @@ export interface CustomTool {/** Serialized tool definition sent to backend for search indexing. Uses official client type. */export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;+export type CustomToolWireDefinition = CustomToolDefinition & {+ preload?: boolean;+};+// ────────────────────────────────────────────────────────────────// Custom toolkit types// ────────────────────────────────────────────────────────────────@@ -186,6 +201,12 @@ export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;export const CreateCustomToolkitBaseSchema = z.object({name: z.string().min(1, 'createCustomToolkit: name is required'),description: z.string().min(1, 'createCustomToolkit: description is required'),+ preload: z+ .boolean()+ .optional()+ .describe(+ 'When true, expose tools in this custom toolkit directly from session.tools(). Tool-level preload values override this default.'+ ),});/** Options for creating a custom toolkit via `createCustomToolkit()`. */@@ -202,12 +223,27 @@ export interface CustomToolkit {readonly slug: string;readonly name: string;readonly description: string;+ /**+ * Default direct-exposure setting for tools in this custom toolkit.+ * Tool-level preload values override this default.+ */+ readonly preload?: boolean;readonly tools: readonly CustomTool[];}/** Serialized toolkit definition sent to backend. Uses official client type. */export type CustomToolkitDefinition = SessionCreateParams.Experimental.CustomToolkit;+export type CustomToolkitWireDefinition = Omit<CustomToolkitDefinition, 'tools'> & {+ preload?: boolean;+ tools: Array<CustomToolkitDefinition['tools'][number] & { preload?: boolean }>;+};++export interface InlineCustomToolsWirePayload {+ custom_tools?: CustomToolWireDefinition[];+ custom_toolkits?: CustomToolkitWireDefinition[];+}+// ────────────────────────────────────────────────────────────────// Internal routing types// ────────────────────────────────────────────────────────────────diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.tsindex 988294859..143b844f9 100644--- a/ts/packages/core/src/types/toolRouter.types.ts+++ b/ts/packages/core/src/types/toolRouter.types.ts@@ -7,6 +7,7 @@ import type { SessionCreateResponse } from '@composio/client/resources/tool-routimport type {CustomTool,CustomToolkit,+ InlineCustomToolsWirePayload,RegisteredCustomTool,RegisteredCustomToolkit,} from './customTool.types';@@ -575,6 +576,7 @@ export interface ToolRouterSessionMetadata {configVersion?: number;warnings?: ToolRouterSessionWarning[];preloadedCustomToolSlugs?: string[];+ inlineCustomToolsPayload?: InlineCustomToolsWirePayload;}export const SessionProxyExecuteParamsSchema = z.object({diff --git a/ts/packages/core/test/models/customToolRouting.test.ts b/ts/packages/core/test/models/customToolRouting.test.tsindex 1c70c1e8b..6b12676e6 100644--- a/ts/packages/core/test/models/customToolRouting.test.ts+++ b/ts/packages/core/test/models/customToolRouting.test.ts@@ -166,6 +166,25 @@ describe('ToolRouter.create() with customTools', () => {expect(payload.experimental.custom_tools[0].extends_toolkit).toBe('meta_ads');});+ it('should send custom tool preload hints under experimental', async () => {+ const preloadedTool = createCustomTool('PINNED_CONTEXT', {+ name: 'Pinned context',+ description: 'Retrieve pinned user context',+ preload: true,+ inputParams: z.object({}),+ execute: localExecute,+ });++ await router.create('user_1', {+ experimental: {+ customTools: [preloadedTool],+ },+ });++ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];+ expect(payload.experimental.custom_tools[0].preload).toBe(true);+ });+it('should not send experimental.custom_tools when customTools is omitted or empty', async () => {await router.create('user_1', { toolkits: ['gmail'] });const payload1 = mockClient.toolRouter.session.create.mock.calls[0][0];diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.tsindex 3569291e1..56b81e27b 100644--- a/ts/packages/core/test/models/toolRouter.test.ts+++ b/ts/packages/core/test/models/toolRouter.test.ts@@ -296,6 +296,23 @@ describe('ToolRouter', () => {expect(session.preload.tools).toBe('all');});+ it('should reject custom tool slugs in top-level preload', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ inputParams: z.object({ pattern: z.string() }),+ execute: vi.fn(async () => ({ matches: [] })),+ });++ await expect(+ toolRouter.create(userId, {+ preload: { tools: ['GREP'] },+ experimental: { customTools: [grepTool] },+ })+ ).rejects.toThrow('Set preload: true on the SDK custom tool');+ expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();+ });+it('should apply the direct_tools session preset defaults', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce({...mockSessionCreateResponse,@@ -365,6 +382,42 @@ describe('ToolRouter', () => {expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);});+ it('should not apply direct_tools custom preload default when preload is explicitly overridden', 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,+ config: {+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },+ },+ experimental: {+ custom_tools: [+ {+ slug: 'SERVER_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });++ await toolRouter.create(userId, {+ sessionPreset: 'direct_tools',+ toolkits: ['github'],+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },+ experimental: { customTools: [grepTool] },+ });++ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];+ expect(payload.preload).toEqual({ tools: ['GITHUB_CREATE_ISSUE'] });+ expect(payload.experimental?.custom_tools?.[0]).not.toHaveProperty('preload');+ });+it('should create a session with user ID only and verify MCP type transformation', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);@@ -2164,6 +2217,47 @@ describe('ToolRouter', () => {});});+ it('should pass inline custom tools to search', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ preload: true,+ inputParams: z.object({ pattern: z.string() }),+ execute: vi.fn(async () => ({ matches: [] })),+ });+ mockClient.toolRouter.session.create.mockResolvedValueOnce({+ ...mockSessionCreateResponse,+ experimental: {+ custom_tools: [+ {+ slug: 'LOCAL_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });+ mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);++ const session = await toolRouter.create(userId, {+ experimental: { customTools: [grepTool] },+ });+ await session.search({ query: 'search local text' });++ expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(sessionId, {+ queries: [{ use_case: 'search local text' }],+ experimental: {+ custom_tools: [+ expect.objectContaining({+ slug: 'GREP',+ preload: true,+ }),+ ],+ custom_toolkits: undefined,+ },+ });+ });+it('should propagate search API errors', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);mockClient.toolRouter.session.search.mockRejectedValueOnce(new Error('Search failed'));@@ -2343,10 +2437,11 @@ describe('ToolRouter', () => {expect(tools).toBe('mocked-wrapped-tools');});- it('should include preloaded custom tools selected by the create response', async () => {+ it('should include custom tools with preload enabled locally', async () => {const grepTool = createCustomTool('GREP', {name: 'Grep',description: 'Search local text',+ preload: true,inputParams: z.object({pattern: z.string().describe('Pattern to search for'),}),@@ -2355,7 +2450,7 @@ describe('ToolRouter', () => {mockClient.toolRouter.session.create.mockResolvedValueOnce({...mockSessionCreateResponse,- tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'server_grep'],+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],experimental: {custom_tools: [{@@ -2385,7 +2480,7 @@ describe('ToolRouter', () => {expect(tools).toBe('mocked-custom-tools');});- it('should not expose custom tools unless the backend preloaded them', async () => {+ it('should not expose custom tools unless SDK preload selects them', async () => {const grepTool = createCustomTool('GREP', {name: 'Grep',description: 'Search local text',@@ -2411,7 +2506,6 @@ describe('ToolRouter', () => {mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');const session = await toolRouter.create(userId, {- preload: { tools: 'all' },experimental: { customTools: [grepTool] },});await session.tools();@@ -2420,6 +2514,41 @@ describe('ToolRouter', () => {expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);});+ it('should expose custom tools by default for preload all', 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', 'LOCAL_GREP']);+ });+it('should handle tools fetching errors', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);