Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 22:15 UTC
Support SDK-local custom tool preload
Dhawal Upadhyay committed
May 6, 2026 at 15:51 UTC
847a8a04a63621cdc5803a000fa8eeea40236fe3
13 files changed
+565
-60
python/composio/core/models/custom_tool.py
+116
-17
@@ -156,6 +156,7 @@ def _create_tool(
156
execute: CustomToolExecuteFn,
157
extends_toolkit: t.Optional[str] = None,
158
output_params: t.Optional[t.Type[BaseModel]] = None,
159
+ preload: t.Optional[bool] = None,
160
) -> CustomTool:
161
"""Internal: create and validate a CustomTool."""
162
context = "experimental.tool"
@@ -218,6 +219,7 @@ def _create_tool(
219
output_schema=output_schema,
220
input_params=input_params,
221
execute=execute,
222
+ preload=preload,
223
)
224
225
@@ -258,6 +260,7 @@ def _infer_tool_from_function(
260
description: t.Optional[str] = None,
261
extends_toolkit: t.Optional[str] = None,
262
output_params: t.Optional[t.Type[BaseModel]] = None,
263
+ preload: t.Optional[bool] = None,
264
annotation_locals: t.Optional[t.Mapping[str, t.Any]] = None,
265
) -> CustomTool:
266
"""Create a CustomTool by inferring metadata from a decorated function.
@@ -341,6 +344,7 @@ def _infer_tool_from_function(
344
execute=execute,
345
extends_toolkit=extends_toolkit,
346
output_params=output_params,
347
+ preload=preload,
348
)
349
350
@@ -372,7 +376,14 @@ class ExperimentalToolkit:
376
return {"results": []}
377
"""
378
375
- def __init__(self, *, slug: str, name: str, description: str) -> None:
379
+ def __init__(
380
+ self,
381
+ *,
382
+ slug: str,
383
+ name: str,
384
+ description: str,
385
+ preload: t.Optional[bool] = None,
386
+ ) -> None:
387
context = "experimental.Toolkit"
388
_validate_slug(slug, context)
389
if not name:
@@ -383,6 +394,7 @@ class ExperimentalToolkit:
394
self.slug = slug
395
self.name = name
396
self.description = description
397
+ self.preload = preload
398
self._tools: t.List[CustomTool] = []
399
400
@property
@@ -400,6 +412,7 @@ class ExperimentalToolkit:
412
name: t.Optional[str] = None,
413
description: t.Optional[str] = None,
414
output_params: t.Optional[t.Type[BaseModel]] = None,
415
+ preload: t.Optional[bool] = None,
416
) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
417
418
def tool(
@@ -410,6 +423,7 @@ class ExperimentalToolkit:
423
name: t.Optional[str] = None,
424
description: t.Optional[str] = None,
425
output_params: t.Optional[t.Type[BaseModel]] = None,
426
+ preload: t.Optional[bool] = None,
427
) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
428
"""Decorator to add a tool to this toolkit.
429
@@ -425,6 +439,7 @@ class ExperimentalToolkit:
439
name=name,
440
description=description,
441
output_params=output_params,
442
+ preload=preload,
443
annotation_locals=annotation_locals,
444
# No extends_toolkit for toolkit tools
445
)
@@ -441,6 +456,7 @@ class ExperimentalToolkit:
456
name=name,
457
description=description,
458
output_params=output_params,
459
+ preload=preload,
460
annotation_locals=_get_caller_locals(),
461
)
462
_validate_slug_length(
@@ -479,6 +495,7 @@ class ExperimentalAPI:
495
description: t.Optional[str] = None,
496
extends_toolkit: t.Optional[str] = None,
497
output_params: t.Optional[t.Type[BaseModel]] = None,
498
+ preload: t.Optional[bool] = None,
499
) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...
500
501
def tool(
@@ -490,6 +507,7 @@ class ExperimentalAPI:
507
description: t.Optional[str] = None,
508
extends_toolkit: t.Optional[str] = None,
509
output_params: t.Optional[t.Type[BaseModel]] = None,
510
+ preload: t.Optional[bool] = None,
511
) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:
512
"""Decorator to create a custom tool from a function.
513
@@ -526,6 +544,7 @@ class ExperimentalAPI:
544
description=description,
545
extends_toolkit=extends_toolkit,
546
output_params=output_params,
547
+ preload=preload,
548
annotation_locals=annotation_locals,
549
)
550
@@ -537,6 +556,7 @@ class ExperimentalAPI:
556
description=description,
557
extends_toolkit=extends_toolkit,
558
output_params=output_params,
559
+ preload=preload,
560
annotation_locals=_get_caller_locals(),
561
)
562
return decorator
@@ -547,7 +567,28 @@ class ExperimentalAPI:
567
# ────────────────────────────────────────────────────────────────
568
569
550
-def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.Any]]:
570
+def _serialized_preload_value(
571
+ preload: t.Optional[bool],
572
+ inherited_preload: t.Optional[bool],
573
+ default_preload: bool,
574
+) -> t.Optional[bool]:
575
+ resolved = (
576
+ preload
577
+ if preload is not None
578
+ else inherited_preload
579
+ if inherited_preload is not None
580
+ else default_preload
581
+ )
582
+ if preload is not None or inherited_preload is not None or default_preload:
583
+ return resolved
584
+ return None
585
+
586
+
587
+def serialize_custom_tools(
588
+ tools: t.List[CustomTool],
589
+ *,
590
+ default_preload: bool = False,
591
+) -> t.List[t.Dict[str, t.Any]]:
592
"""Serialize custom tools into the format expected by the backend."""
593
result = []
594
for tool in tools:
@@ -561,12 +602,19 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.An
602
entry["output_schema"] = tool.output_schema
603
if tool.extends_toolkit:
604
entry["extends_toolkit"] = tool.extends_toolkit
605
+ preload = _serialized_preload_value(
606
+ tool.preload, inherited_preload=None, default_preload=default_preload
607
+ )
608
+ if preload is not None:
609
+ entry["preload"] = preload
610
result.append(entry)
611
return result
612
613
614
def serialize_custom_toolkits(
615
toolkits: t.Sequence[ExperimentalToolkit],
616
+ *,
617
+ default_preload: bool = False,
618
) -> t.List[t.Dict[str, t.Any]]:
619
"""Serialize custom toolkits into the format expected by the backend."""
620
result = []
@@ -581,15 +629,26 @@ def serialize_custom_toolkits(
629
}
630
if tool.output_schema:
631
entry["output_schema"] = tool.output_schema
632
+ preload = _serialized_preload_value(
633
+ tool.preload,
634
+ inherited_preload=tk.preload,
635
+ default_preload=default_preload,
636
+ )
637
+ if preload is not None:
638
+ entry["preload"] = preload
639
toolkit_tools.append(entry)
585
- result.append(
586
- {
587
- "slug": tk.slug,
588
- "name": tk.name,
589
- "description": tk.description,
590
- "tools": toolkit_tools,
591
- }
640
+ toolkit_entry: t.Dict[str, t.Any] = {
641
+ "slug": tk.slug,
642
+ "name": tk.name,
643
+ "description": tk.description,
644
+ "tools": toolkit_tools,
645
+ }
646
+ preload = _serialized_preload_value(
647
+ tk.preload, inherited_preload=None, default_preload=default_preload
648
)
649
+ if preload is not None:
650
+ toolkit_entry["preload"] = preload
651
+ result.append(toolkit_entry)
652
return result
653
654
@@ -729,23 +788,63 @@ def find_custom_tool_map_entry_by_final_slug(
788
return custom_tools_map.by_final_slug.get(slug.upper())
789
790
791
+def assert_no_custom_tool_slugs_in_preload(
792
+ preload_tools: t.Union[t.Sequence[str], t.Literal["all"], None],
793
+ custom_tools_map: t.Optional[CustomToolsMap],
794
+) -> None:
795
+ """Reject legacy top-level preload of custom tool slugs."""
796
+ if preload_tools is None or preload_tools == "all":
797
+ return
798
+
799
+ custom_preload_slugs = []
800
+ for slug in preload_tools:
801
+ normalized = slug.upper()
802
+ if normalized.startswith(LOCAL_TOOL_PREFIX) or (
803
+ custom_tools_map is not None
804
+ and (
805
+ normalized in custom_tools_map.by_original_slug
806
+ or normalized in custom_tools_map.by_final_slug
807
+ )
808
+ ):
809
+ custom_preload_slugs.append(slug)
810
+
811
+ if custom_preload_slugs:
812
+ raise ValidationError(
813
+ "Custom tool slugs are not supported in preload.tools: "
814
+ f"{', '.join(custom_preload_slugs)}. Set preload=True on the SDK "
815
+ "custom tool or custom toolkit definition instead."
816
+ )
817
+
818
+
819
def get_preloaded_custom_tool_slugs(
733
- tool_router_tools: t.Optional[t.Iterable[str]],
820
custom_tools_map: t.Optional[CustomToolsMap],
821
+ *,
822
+ default_preload: bool = False,
823
) -> t.List[str]:
736
- """Return final custom tool slugs selected by the backend for preload."""
737
- if tool_router_tools is None or custom_tools_map is None:
824
+ """Return final custom tool slugs selected locally for preload."""
825
+ if custom_tools_map is None:
826
return []
827
828
seen: t.Set[str] = set()
829
custom_tool_slugs: t.List[str] = []
830
743
- for slug in tool_router_tools:
744
- entry = find_custom_tool_map_entry_by_final_slug(
745
- custom_tools_map,
746
- str(slug),
831
+ for entry in custom_tools_map.by_final_slug.values():
832
+ toolkit = next(
833
+ (
834
+ tk
835
+ for tk in custom_tools_map.toolkits or []
836
+ if entry.toolkit and tk.slug.lower() == entry.toolkit.lower()
837
+ ),
838
+ None,
839
+ )
840
+ should_preload = (
841
+ entry.handle.preload
842
+ if entry.handle.preload is not None
843
+ else toolkit.preload
844
+ if toolkit is not None and toolkit.preload is not None
845
+ else default_preload
846
)
748
- if entry is None:
847
+ if not should_preload:
848
continue
849
850
final_slug_key = entry.final_slug.upper()
python/composio/core/models/custom_tool_types.py
+1
@@ -106,6 +106,7 @@ class CustomTool:
106
execute: CustomToolExecuteFn
107
extends_toolkit: t.Optional[str] = None
108
output_schema: t.Optional[t.Dict[str, t.Any]] = None
109
+ preload: t.Optional[bool] = None
110
111
112
# ────────────────────────────────────────────────────────────────
python/composio/core/models/tool_router.py
+33
-3
@@ -19,6 +19,8 @@ from composio.client import HttpClient
19
from composio.core.models.base import Resource
20
from composio.core.models.custom_tool import (
21
ExperimentalToolkit,
22
+ assert_no_custom_tool_slugs_in_preload,
23
+ build_custom_tools_map,
24
build_custom_tools_map_from_response,
25
get_preloaded_custom_tool_slugs,
26
serialize_custom_tools,
@@ -627,6 +629,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
629
- 'assistive_prompt' (dict): Configuration for assistive prompt generation.
630
- 'user_timezone' (str): IANA timezone identifier
631
(e.g., "America/New_York", "Europe/London").
632
+ - 'custom_tools' / 'custom_toolkits': SDK custom tools.
633
+ Set preload=True on a custom tool or toolkit to expose
634
+ it directly from session.tools(); otherwise custom tools
635
+ remain search-only.
636
Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}
637
:return: Tool router session object
638
@@ -716,6 +722,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
722
workbench=workbench,
723
preload=preload,
724
)
725
+ default_custom_preload = preload is not None and preload.get("tools") == "all"
726
727
# Parse manage_connections config
728
manage_connections = (
@@ -851,6 +858,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
858
# experimental.assistive_prompt_config.user_timezone
859
custom_tools: t.Optional[t.List[CustomTool]] = None
860
custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None
861
+ local_custom_tools_map: t.Optional[CustomToolsMap] = None
862
+ inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None
863
864
if experimental is not None:
865
experimental_payload: t.Dict[str, t.Any] = {}
@@ -866,16 +875,36 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
875
# Serialize custom tools and toolkits for the backend
876
custom_tools = experimental.get("custom_tools")
877
custom_toolkits = experimental.get("custom_toolkits")
878
+ if custom_tools or custom_toolkits:
879
+ local_custom_tools_map = build_custom_tools_map(
880
+ custom_tools or [],
881
+ custom_toolkits,
882
+ )
883
+ assert_no_custom_tool_slugs_in_preload(
884
+ preload.get("tools") if preload is not None else None,
885
+ local_custom_tools_map,
886
+ )
887
888
if custom_tools:
889
experimental_payload["custom_tools"] = serialize_custom_tools(
872
- custom_tools
890
+ custom_tools,
891
+ default_preload=default_custom_preload,
892
)
893
if custom_toolkits:
894
experimental_payload["custom_toolkits"] = serialize_custom_toolkits(
876
- custom_toolkits
895
+ custom_toolkits,
896
+ default_preload=default_custom_preload,
897
)
898
899
+ if (
900
+ "custom_tools" in experimental_payload
901
+ or "custom_toolkits" in experimental_payload
902
+ ):
903
+ inline_custom_tools_payload = {
904
+ "custom_tools": experimental_payload.get("custom_tools"),
905
+ "custom_toolkits": experimental_payload.get("custom_toolkits"),
906
+ }
907
+
908
if experimental_payload:
909
create_params["experimental"] = experimental_payload
910
@@ -897,8 +926,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
926
experimental=session.experimental,
927
)
928
preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(
900
- getattr(session, "tool_router_tools", None),
929
custom_tools_map,
930
+ default_preload=default_custom_preload,
931
)
932
933
# Transform experimental response:
@@ -930,6 +959,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
959
user_id=user_id,
960
preload=_session_preload_config(session),
961
preloaded_custom_tool_slugs=preloaded_custom_tool_slugs,
962
+ inline_custom_tools_payload=inline_custom_tools_payload,
963
)
964
965
def use(self, session_id: str) -> ToolRouterSession[TTool, TToolCollection]:
python/composio/core/models/tool_router_session.py
+19
-11
@@ -105,6 +105,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
105
user_id: t.Optional[str] = None,
106
preload: t.Optional[ToolRouterSessionPreloadConfig] = None,
107
preloaded_custom_tool_slugs: t.Optional[t.List[str]] = None,
108
+ inline_custom_tools_payload: t.Optional[t.Dict[str, t.Any]] = None,
109
) -> None:
110
self._client = client
111
self._provider = provider
@@ -119,6 +120,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
120
self._custom_tools_map = custom_tools_map
121
self._user_id = user_id
122
self._preloaded_custom_tool_slugs = preloaded_custom_tool_slugs or []
123
+ self._inline_custom_tools_payload = inline_custom_tools_payload
124
125
# Create singleton session context if custom tools are bound
126
self._session_context: t.Optional[SessionContextImpl] = None
@@ -634,11 +636,14 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
636
637
Returns relevant tools for the given query with schemas and guidance.
638
"""
637
- return self._client.tool_router.session.search(
638
- session_id=self.session_id,
639
- queries=[{"use_case": query}],
640
- model=model if model else omit,
641
- )
639
+ params: t.Dict[str, t.Any] = {
640
+ "session_id": self.session_id,
641
+ "queries": [{"use_case": query}],
642
+ "model": model if model else omit,
643
+ }
644
+ if self._inline_custom_tools_payload is not None:
645
+ params["experimental"] = self._inline_custom_tools_payload
646
+ return self._client.tool_router.session.search(**params)
647
648
def execute(
649
self,
@@ -676,12 +681,15 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
681
)
682
683
# Remote execution
679
- return self._client.tool_router.session.execute(
680
- session_id=self.session_id,
681
- tool_slug=tool_slug,
682
- arguments=arguments if arguments is not None else omit,
683
- account=account if account is not None else omit,
684
- )
684
+ params: t.Dict[str, t.Any] = {
685
+ "session_id": self.session_id,
686
+ "tool_slug": tool_slug,
687
+ "arguments": arguments if arguments is not None else omit,
688
+ "account": account if account is not None else omit,
689
+ }
690
+ if self._inline_custom_tools_payload is not None:
691
+ params["experimental"] = self._inline_custom_tools_payload
692
+ return self._client.tool_router.session.execute(**params)
693
694
def custom_tools(
695
self, *, toolkit: t.Optional[str] = None
python/tests/test_custom_tools.py
+20
@@ -12,6 +12,7 @@ Covers:
12
- Multi-execute routing (all-local, all-remote, mixed, parallel)
13
"""
14
15
+from dataclasses import replace
16
from unittest.mock import MagicMock
17
18
import pytest
@@ -145,6 +146,14 @@ class TestDecoratorTool:
146
147
assert fetch_mail.extends_toolkit == "gmail"
148
149
+ def test_decorator_with_preload(self):
150
+ @exp.tool(preload=True)
151
+ def fetch_context(input: GrepInput, ctx):
152
+ """Fetch context."""
153
+ return {}
154
+
155
+ assert fetch_context.preload is True
156
+
157
def test_decorator_explicit_overrides(self):
158
@exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
159
def whatever(input: GrepInput, ctx):
@@ -408,12 +417,23 @@ class TestSerialization:
417
result = serialize_custom_tools([email_tool])
418
assert result[0]["extends_toolkit"] == "gmail"
419
420
+ def test_serialize_custom_tool_preload_hint(self, grep_tool):
421
+ preloaded = replace(grep_tool, preload=True)
422
+ result = serialize_custom_tools([preloaded])
423
+ assert result[0]["preload"] is True
424
+
425
def test_serialize_toolkit(self, role_toolkit):
426
result = serialize_custom_toolkits([role_toolkit])
427
assert len(result) == 1
428
assert result[0]["slug"] == "ROLE_MANAGER"
429
assert len(result[0]["tools"]) == 1
430
431
+ def test_serialize_toolkit_preload_hint(self, role_toolkit):
432
+ role_toolkit.preload = True
433
+ result = serialize_custom_toolkits([role_toolkit])
434
+ assert result[0]["preload"] is True
435
+ assert result[0]["tools"][0]["preload"] is True
436
+
437
438
# ────────────────────────────────────────────────────────────────
439
# Routing map tests
python/tests/test_tool_router.py
+63
-2
@@ -5,6 +5,7 @@ from unittest.mock import MagicMock, patch
5
import pytest
6
from pydantic import BaseModel, Field
7
8
+from composio.exceptions import ValidationError
9
from composio.core.models.custom_tool import ExperimentalAPI
10
from composio.core.models.tool_router import (
11
ToolkitConnectionsDetails,
@@ -628,6 +629,29 @@ class TestToolRouter:
629
assert kwargs["preload"] == {"tools": "all"}
630
assert session.preload.tools == "all"
631
632
+ def test_create_session_rejects_custom_slug_in_top_level_preload(
633
+ self, tool_router, mock_client
634
+ ):
635
+ @experimental_api.tool(
636
+ slug="GREP",
637
+ name="Grep",
638
+ description="Search local text",
639
+ )
640
+ def grep(input: GrepInput, ctx):
641
+ return {"matches": []}
642
+
643
+ with pytest.raises(
644
+ ValidationError,
645
+ match="Set preload=True on the SDK custom tool",
646
+ ):
647
+ tool_router.create(
648
+ user_id="user_123",
649
+ preload={"tools": ["GREP"]},
650
+ experimental={"custom_tools": [grep]},
651
+ )
652
+
653
+ mock_client.tool_router.session.create.assert_not_called()
654
+
655
def test_create_session_with_direct_tools_preset(self, tool_router, mock_client):
656
"""direct_tools applies SDK-side defaults for direct tool exposure."""
657
mock_client.tool_router.session.create.return_value.config.preload.tools = "all"
@@ -672,6 +696,42 @@ class TestToolRouter:
696
assert kwargs["execute"] == {"enable_multi_execute": False}
697
assert session.preload.tools == ["GITHUB_CREATE_ISSUE"]
698
699
+ def test_direct_tools_does_not_default_custom_preload_when_preload_overridden(
700
+ self, tool_router, mock_client
701
+ ):
702
+ """Explicit preload config also overrides the custom-tool preload default."""
703
+
704
+ @experimental_api.tool(
705
+ slug="GREP",
706
+ name="Grep",
707
+ description="Search local text",
708
+ )
709
+ def grep(input: GrepInput, ctx):
710
+ return {"matches": []}
711
+
712
+ mock_response = mock_client.tool_router.session.create.return_value
713
+ mock_response.config.preload.tools = ["GITHUB_CREATE_ISSUE"]
714
+ mock_response.experimental = MagicMock()
715
+ mock_response.experimental.assistive_prompt = None
716
+ mock_response.experimental.custom_toolkits = []
717
+ mock_custom_tool = MagicMock()
718
+ mock_custom_tool.slug = "SERVER_GREP"
719
+ mock_custom_tool.original_slug = "GREP"
720
+ mock_custom_tool.extends_toolkit = None
721
+ mock_response.experimental.custom_tools = [mock_custom_tool]
722
+
723
+ tool_router.create(
724
+ user_id="user_123",
725
+ session_preset="direct_tools",
726
+ toolkits=["github"],
727
+ preload={"tools": ["GITHUB_CREATE_ISSUE"]},
728
+ experimental={"custom_tools": [grep]},
729
+ )
730
+
731
+ kwargs = mock_client.tool_router.session.create.call_args.kwargs
732
+ assert kwargs["preload"] == {"tools": ["GITHUB_CREATE_ISSUE"]}
733
+ assert "preload" not in kwargs["experimental"]["custom_tools"][0]
734
+
735
def test_create_session_complex_config(self, tool_router, mock_client):
736
"""Test creating a session with complex configuration."""
737
session = tool_router.create(
@@ -1149,18 +1209,19 @@ class TestToolRouter:
1209
mock_client,
1210
mock_provider,
1211
):
1152
- """Custom tools preloaded by the create response are exposed locally."""
1212
+ """Custom tools with SDK preload enabled are exposed locally."""
1213
1214
@experimental_api.tool(
1215
slug="GREP",
1216
name="Grep",
1217
description="Search local text",
1218
+ preload=True,
1219
)
1220
def grep(input: GrepInput, ctx):
1221
return {"matches": []}
1222
1223
mock_response = mock_client.tool_router.session.create.return_value
1163
- mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS", "server_grep"]
1224
+ mock_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]
1225
mock_response.experimental = MagicMock()
1226
mock_response.experimental.assistive_prompt = None
1227
mock_response.experimental.custom_toolkits = []
ts/packages/core/src/models/CustomTool.ts
+86
-14
@@ -32,8 +32,8 @@ import {
32
type CustomToolExecuteFn,
33
type CustomToolsMap,
34
type CustomToolsMapEntry,
35
- type CustomToolDefinition,
36
- type CustomToolkitDefinition,
35
+ type CustomToolWireDefinition,
36
+ type CustomToolkitWireDefinition,
37
type InputParamsSchema,
38
} from '../types/customTool.types';
39
import type { SessionCreateResponse } from '@composio/client/resources/tool-router/session/session.mjs';
@@ -184,6 +184,7 @@ export function createCustomTool<T extends z.ZodType>(
184
name: validated.name,
185
description: validated.description,
186
extendsToolkit: validated.extendsToolkit,
187
+ preload: validated.preload,
188
inputSchema,
189
outputSchema,
190
inputParams,
@@ -250,6 +251,7 @@ export function createCustomToolkit(
251
slug: slugResult.data,
252
name: validated.name,
253
description: validated.description,
254
+ preload: validated.preload,
255
tools: options.tools,
256
};
257
}
@@ -340,7 +342,36 @@ export function buildCustomToolsMap(
342
* @param tools - The custom tools to serialize
343
* @returns Array of CustomToolDefinition for the API payload
344
*/
343
-export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[] {
345
+type CustomToolSerializationOptions = {
346
+ defaultPreload?: boolean;
347
+};
348
+
349
+function shouldSerializePreload(
350
+ preload: boolean | undefined,
351
+ inheritedPreload: boolean | undefined,
352
+ defaultPreload: boolean
353
+): boolean | undefined {
354
+ const resolved = preload ?? inheritedPreload ?? defaultPreload;
355
+ if (preload !== undefined || inheritedPreload !== undefined || defaultPreload) {
356
+ return resolved;
357
+ }
358
+ return undefined;
359
+}
360
+
361
+function preloadWireProperty(
362
+ preload: boolean | undefined,
363
+ inheritedPreload: boolean | undefined,
364
+ defaultPreload: boolean
365
+): { preload?: boolean } {
366
+ const serializedPreload = shouldSerializePreload(preload, inheritedPreload, defaultPreload);
367
+ return serializedPreload === undefined ? {} : { preload: serializedPreload };
368
+}
369
+
370
+export function serializeCustomTools(
371
+ tools: CustomTool[],
372
+ options: CustomToolSerializationOptions = {}
373
+): CustomToolWireDefinition[] {
374
+ const defaultPreload = options.defaultPreload ?? false;
375
return tools.map(handle => ({
376
slug: handle.slug,
377
name: handle.name,
@@ -348,6 +379,7 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[
379
input_schema: handle.inputSchema,
380
...(handle.outputSchema ? { output_schema: handle.outputSchema } : {}),
381
...(handle.extendsToolkit ? { extends_toolkit: handle.extendsToolkit } : {}),
382
+ ...preloadWireProperty(handle.preload, undefined, defaultPreload),
383
}));
384
}
385
@@ -358,17 +390,23 @@ export function serializeCustomTools(tools: CustomTool[]): CustomToolDefinition[
390
* @param toolkits - The custom toolkits to serialize
391
* @returns Array of CustomToolkitDefinition for the API payload
392
*/
361
-export function serializeCustomToolkits(toolkits: CustomToolkit[]): CustomToolkitDefinition[] {
393
+export function serializeCustomToolkits(
394
+ toolkits: CustomToolkit[],
395
+ options: CustomToolSerializationOptions = {}
396
+): CustomToolkitWireDefinition[] {
397
+ const defaultPreload = options.defaultPreload ?? false;
398
return toolkits.map(tk => ({
399
slug: tk.slug,
400
name: tk.name,
401
description: tk.description,
402
+ ...preloadWireProperty(tk.preload, undefined, defaultPreload),
403
tools: tk.tools.map(t => ({
404
slug: t.slug,
405
name: t.name,
406
description: t.description,
407
input_schema: t.inputSchema,
408
...(t.outputSchema ? { output_schema: t.outputSchema } : {}),
409
+ ...preloadWireProperty(t.preload, tk.preload, defaultPreload),
410
})),
411
}));
412
}
@@ -452,28 +490,62 @@ export function findCustomToolMapEntryByFinalSlug(
490
}
491
492
/**
455
- * Resolve custom tools that the backend selected for direct preload.
493
+ * Reject legacy attempts to preload custom tools through top-level preload.tools.
494
*
457
- * The backend is the source of truth for preload expansion, including "all".
458
- * The SDK only keeps the final custom slugs it can serve locally because
459
- * the session tools endpoint only returns backend-managed tool schemas.
495
+ * Custom tool direct exposure is controlled by CustomTool.preload /
496
+ * CustomToolkit.preload so it follows the current SDK-provided custom
497
+ * definitions instead of stale session config.
498
*
499
* @internal
500
*/
463
-export function getPreloadedCustomToolSlugs(
464
- toolRouterTools: readonly string[] | undefined,
501
+export function assertNoCustomToolSlugsInPreload(
502
+ preloadTools: readonly string[] | 'all' | undefined,
503
customToolsMap: CustomToolsMap | undefined
504
+): void {
505
+ if (!preloadTools || preloadTools === 'all') {
506
+ return;
507
+ }
508
+
509
+ const customPreloadSlugs = preloadTools.filter(slug => {
510
+ const normalized = slug.toUpperCase();
511
+ return (
512
+ normalized.startsWith(LOCAL_TOOL_PREFIX) ||
513
+ customToolsMap?.byOriginalSlug.has(normalized) ||
514
+ customToolsMap?.byFinalSlug.has(normalized)
515
+ );
516
+ });
517
+
518
+ if (customPreloadSlugs.length) {
519
+ throw new ValidationError(
520
+ `Custom tool slugs are not supported in preload.tools: ${customPreloadSlugs.join(
521
+ ', '
522
+ )}. Set preload: true on the SDK custom tool or custom toolkit definition instead.`
523
+ );
524
+ }
525
+}
526
+
527
+/**
528
+ * Resolve custom tools that the SDK should expose directly from session.tools().
529
+ *
530
+ * @internal
531
+ */
532
+export function getPreloadedCustomToolSlugs(
533
+ customToolsMap: CustomToolsMap | undefined,
534
+ defaultPreload = false
535
): string[] {
467
- if (!toolRouterTools?.length || !customToolsMap) {
536
+ if (!customToolsMap) {
537
return [];
538
}
539
540
const seen = new Set<string>();
541
const customToolSlugs: string[] = [];
542
474
- for (const slug of toolRouterTools) {
475
- const entry = findCustomToolMapEntryByFinalSlug(customToolsMap, slug);
476
- if (!entry) {
543
+ for (const entry of customToolsMap.byFinalSlug.values()) {
544
+ const toolkit = customToolsMap.toolkits?.find(
545
+ tk => entry.toolkit && tk.slug.toLowerCase() === entry.toolkit.toLowerCase()
546
+ );
547
+ const shouldPreload = entry.handle.preload ?? toolkit?.preload ?? defaultPreload;
548
+ if (!shouldPreload) {
549
continue;
550
}
551
ts/packages/core/src/models/ToolRouter.ts
+26
-6
@@ -45,6 +45,8 @@ import {
45
} from '../lib/toolRouterParams';
46
import { ToolRouterSession } from './ToolRouterSession';
47
import {
48
+ assertNoCustomToolSlugsInPreload,
49
+ buildCustomToolsMap,
50
buildCustomToolsMapFromResponse,
51
getPreloadedCustomToolSlugs,
52
serializeCustomTools,
@@ -111,6 +113,9 @@ export class ToolRouter<
113
* },
114
* });
115
*
116
+ * // Custom tools are searched by default. Set `preload: true` on a custom
117
+ * // tool or toolkit to expose it directly from `session.tools()`.
118
+ *
119
* // Expose all tools allowed by filters directly, without meta/helper tools.
120
* // `preload.tools = "all"` requires a positive filter such as `toolkits`.
121
* const directSession = await composio.create('user_123', {
@@ -129,6 +134,12 @@ export class ToolRouter<
134
// Extract custom tools/toolkits from experimental config
135
const customTools = routerConfig.experimental?.customTools;
136
const customToolkits = routerConfig.experimental?.customToolkits;
137
+ const defaultCustomPreload = routerConfig.preload?.tools === 'all';
138
+ const localCustomToolsMap =
139
+ customTools?.length || customToolkits?.length
140
+ ? buildCustomToolsMap(customTools ?? [], customToolkits)
141
+ : undefined;
142
+ assertNoCustomToolSlugsInPreload(routerConfig.preload?.tools, localCustomToolsMap);
143
144
// Build the typed experimental payload for the backend
145
const experimentalPayload: SessionCreateParams['experimental'] = {};
@@ -140,11 +151,22 @@ export class ToolRouter<
151
}
152
153
if (customTools?.length) {
143
- experimentalPayload.custom_tools = serializeCustomTools(customTools);
154
+ experimentalPayload.custom_tools = serializeCustomTools(customTools, {
155
+ defaultPreload: defaultCustomPreload,
156
+ });
157
}
158
if (customToolkits?.length) {
146
- experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits);
159
+ experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits, {
160
+ defaultPreload: defaultCustomPreload,
161
+ });
162
}
163
+ const inlineCustomToolsPayload =
164
+ experimentalPayload.custom_tools || experimentalPayload.custom_toolkits
165
+ ? {
166
+ custom_tools: experimentalPayload.custom_tools,
167
+ custom_toolkits: experimentalPayload.custom_toolkits,
168
+ }
169
+ : undefined;
170
171
const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
172
@@ -182,10 +204,8 @@ export class ToolRouter<
204
}
205
const metadata = {
206
...getSessionMetadata(session),
185
- preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(
186
- session.tool_router_tools,
187
- customToolsMap
188
- ),
207
+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),
208
+ inlineCustomToolsPayload,
209
};
210
211
const assistivePrompt = session.experimental?.assistive_prompt;
ts/packages/core/src/models/ToolRouterSession.ts
+11
-3
@@ -39,7 +39,10 @@ import type {
39
} from '../types/customTool.types';
40
import type { Tool, ToolExecuteResponse } from '../types/tool.types';
41
import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
42
-import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
42
+import type {
43
+ SessionExecuteParams,
44
+ SessionSearchParams,
45
+} from '@composio/client/resources/tool-router/session/session.mjs';
46
import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
47
import { SessionContextImpl } from './SessionContext';
48
import { findCustomTool, executeCustomTool } from './customToolExecution';
@@ -62,6 +65,7 @@ export class ToolRouterSession<
65
public readonly configVersion?: number;
66
public readonly warnings: ToolRouterSessionWarning[];
67
private readonly preloadedCustomToolSlugs: string[];
68
+ private readonly inlineCustomToolsPayload: ToolRouterSessionMetadata['inlineCustomToolsPayload'];
69
70
/** Singleton session context — shared across all custom tool executions */
71
private readonly sessionContext?: SessionContext;
@@ -89,6 +93,7 @@ export class ToolRouterSession<
93
this.configVersion = metadata?.configVersion;
94
this.warnings = metadata?.warnings ?? [];
95
this.preloadedCustomToolSlugs = metadata?.preloadedCustomToolSlugs ?? [];
96
+ this.inlineCustomToolsPayload = metadata?.inlineCustomToolsPayload;
97
98
// Create singleton session context if custom tools are bound
99
if (customToolsMap && userId) {
@@ -354,10 +359,12 @@ export class ToolRouterSession<
359
query: string;
360
toolkits?: string[];
361
}): Promise<ToolRouterSessionSearchResponse> {
357
- const response = await this.client.toolRouter.session.search(this.sessionId, {
362
+ const searchParams: SessionSearchParams & { toolkits?: string[] } = {
363
queries: [{ use_case: params.query }],
364
...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
360
- });
365
+ ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),
366
+ };
367
+ const response = await this.client.toolRouter.session.search(this.sessionId, searchParams);
368
const transformed = transformSearchResponse(response);
369
return ToolRouterSessionSearchResponseSchema.parse(transformed);
370
}
@@ -395,6 +402,7 @@ export class ToolRouterSession<
402
const executeParams: SessionExecuteParams = {
403
tool_slug: toolSlug,
404
arguments: arguments_ ?? {},
405
+ ...(this.inlineCustomToolsPayload ? { experimental: this.inlineCustomToolsPayload } : {}),
406
};
407
if (options?.account) {
408
executeParams.account = options.account;
ts/packages/core/src/types/customTool.types.ts
+36
@@ -135,6 +135,12 @@ export const CreateCustomToolBaseSchema = z.object({
135
* Leave empty for tools that don't need any Composio-managed authentication.
136
*/
137
extendsToolkit: z.string().optional(),
138
+ preload: z
139
+ .boolean()
140
+ .optional()
141
+ .describe(
142
+ '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.'
143
+ ),
144
});
145
146
/** Options for creating a custom tool via `createCustomTool()`. */
@@ -163,6 +169,11 @@ export interface CustomTool {
169
* Undefined means the tool doesn't need any Composio-managed authentication.
170
*/
171
readonly extendsToolkit?: string;
172
+ /**
173
+ * Whether this custom tool should be exposed directly from session.tools().
174
+ * This is SDK-local for custom tools and is sent to v3.1 as an input-only hint.
175
+ */
176
+ readonly preload?: boolean;
177
readonly inputSchema: Record<string, unknown>;
178
/** JSON Schema representation of the output (for backend documentation) */
179
readonly outputSchema?: Record<string, unknown>;
@@ -175,6 +186,10 @@ export interface CustomTool {
186
/** Serialized tool definition sent to backend for search indexing. Uses official client type. */
187
export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;
188
189
+export type CustomToolWireDefinition = CustomToolDefinition & {
190
+ preload?: boolean;
191
+};
192
+
193
// ────────────────────────────────────────────────────────────────
194
// Custom toolkit types
195
// ────────────────────────────────────────────────────────────────
@@ -186,6 +201,12 @@ export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;
201
export const CreateCustomToolkitBaseSchema = z.object({
202
name: z.string().min(1, 'createCustomToolkit: name is required'),
203
description: z.string().min(1, 'createCustomToolkit: description is required'),
204
+ preload: z
205
+ .boolean()
206
+ .optional()
207
+ .describe(
208
+ 'When true, expose tools in this custom toolkit directly from session.tools(). Tool-level preload values override this default.'
209
+ ),
210
});
211
212
/** Options for creating a custom toolkit via `createCustomToolkit()`. */
@@ -202,12 +223,27 @@ export interface CustomToolkit {
223
readonly slug: string;
224
readonly name: string;
225
readonly description: string;
226
+ /**
227
+ * Default direct-exposure setting for tools in this custom toolkit.
228
+ * Tool-level preload values override this default.
229
+ */
230
+ readonly preload?: boolean;
231
readonly tools: readonly CustomTool[];
232
}
233
234
/** Serialized toolkit definition sent to backend. Uses official client type. */
235
export type CustomToolkitDefinition = SessionCreateParams.Experimental.CustomToolkit;
236
237
+export type CustomToolkitWireDefinition = Omit<CustomToolkitDefinition, 'tools'> & {
238
+ preload?: boolean;
239
+ tools: Array<CustomToolkitDefinition['tools'][number] & { preload?: boolean }>;
240
+};
241
+
242
+export interface InlineCustomToolsWirePayload {
243
+ custom_tools?: CustomToolWireDefinition[];
244
+ custom_toolkits?: CustomToolkitWireDefinition[];
245
+}
246
+
247
// ────────────────────────────────────────────────────────────────
248
// Internal routing types
249
// ────────────────────────────────────────────────────────────────
ts/packages/core/src/types/toolRouter.types.ts
+2
@@ -7,6 +7,7 @@ import type { SessionCreateResponse } from '@composio/client/resources/tool-rout
7
import type {
8
CustomTool,
9
CustomToolkit,
10
+ InlineCustomToolsWirePayload,
11
RegisteredCustomTool,
12
RegisteredCustomToolkit,
13
} from './customTool.types';
@@ -575,6 +576,7 @@ export interface ToolRouterSessionMetadata {
576
configVersion?: number;
577
warnings?: ToolRouterSessionWarning[];
578
preloadedCustomToolSlugs?: string[];
579
+ inlineCustomToolsPayload?: InlineCustomToolsWirePayload;
580
}
581
582
export const SessionProxyExecuteParamsSchema = z.object({
ts/packages/core/test/models/customToolRouting.test.ts
+19
@@ -166,6 +166,25 @@ describe('ToolRouter.create() with customTools', () => {
166
expect(payload.experimental.custom_tools[0].extends_toolkit).toBe('meta_ads');
167
});
168
169
+ it('should send custom tool preload hints under experimental', async () => {
170
+ const preloadedTool = createCustomTool('PINNED_CONTEXT', {
171
+ name: 'Pinned context',
172
+ description: 'Retrieve pinned user context',
173
+ preload: true,
174
+ inputParams: z.object({}),
175
+ execute: localExecute,
176
+ });
177
+
178
+ await router.create('user_1', {
179
+ experimental: {
180
+ customTools: [preloadedTool],
181
+ },
182
+ });
183
+
184
+ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
185
+ expect(payload.experimental.custom_tools[0].preload).toBe(true);
186
+ });
187
+
188
it('should not send experimental.custom_tools when customTools is omitted or empty', async () => {
189
await router.create('user_1', { toolkits: ['gmail'] });
190
const payload1 = mockClient.toolRouter.session.create.mock.calls[0][0];
ts/packages/core/test/models/toolRouter.test.ts
+133
-4
@@ -296,6 +296,23 @@ describe('ToolRouter', () => {
296
expect(session.preload.tools).toBe('all');
297
});
298
299
+ it('should reject custom tool slugs in top-level preload', async () => {
300
+ const grepTool = createCustomTool('GREP', {
301
+ name: 'Grep',
302
+ description: 'Search local text',
303
+ inputParams: z.object({ pattern: z.string() }),
304
+ execute: vi.fn(async () => ({ matches: [] })),
305
+ });
306
+
307
+ await expect(
308
+ toolRouter.create(userId, {
309
+ preload: { tools: ['GREP'] },
310
+ experimental: { customTools: [grepTool] },
311
+ })
312
+ ).rejects.toThrow('Set preload: true on the SDK custom tool');
313
+ expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
314
+ });
315
+
316
it('should apply the direct_tools session preset defaults', async () => {
317
mockClient.toolRouter.session.create.mockResolvedValueOnce({
318
...mockSessionCreateResponse,
@@ -365,6 +382,42 @@ describe('ToolRouter', () => {
382
expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);
383
});
384
385
+ it('should not apply direct_tools custom preload default when preload is explicitly overridden', async () => {
386
+ const grepTool = createCustomTool('GREP', {
387
+ name: 'Grep',
388
+ description: 'Search local text',
389
+ inputParams: z.object({ pattern: z.string() }),
390
+ execute: vi.fn(async () => ({ matches: [] })),
391
+ });
392
+
393
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
394
+ ...mockSessionCreateResponse,
395
+ config: {
396
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
397
+ },
398
+ experimental: {
399
+ custom_tools: [
400
+ {
401
+ slug: 'SERVER_GREP',
402
+ original_slug: 'GREP',
403
+ extends_toolkit: null,
404
+ },
405
+ ],
406
+ },
407
+ });
408
+
409
+ await toolRouter.create(userId, {
410
+ sessionPreset: 'direct_tools',
411
+ toolkits: ['github'],
412
+ preload: { tools: ['GITHUB_CREATE_ISSUE'] },
413
+ experimental: { customTools: [grepTool] },
414
+ });
415
+
416
+ const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
417
+ expect(payload.preload).toEqual({ tools: ['GITHUB_CREATE_ISSUE'] });
418
+ expect(payload.experimental?.custom_tools?.[0]).not.toHaveProperty('preload');
419
+ });
420
+
421
it('should create a session with user ID only and verify MCP type transformation', async () => {
422
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
423
@@ -2164,6 +2217,47 @@ describe('ToolRouter', () => {
2217
});
2218
});
2219
2220
+ it('should pass inline custom tools to search', async () => {
2221
+ const grepTool = createCustomTool('GREP', {
2222
+ name: 'Grep',
2223
+ description: 'Search local text',
2224
+ preload: true,
2225
+ inputParams: z.object({ pattern: z.string() }),
2226
+ execute: vi.fn(async () => ({ matches: [] })),
2227
+ });
2228
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
2229
+ ...mockSessionCreateResponse,
2230
+ experimental: {
2231
+ custom_tools: [
2232
+ {
2233
+ slug: 'LOCAL_GREP',
2234
+ original_slug: 'GREP',
2235
+ extends_toolkit: null,
2236
+ },
2237
+ ],
2238
+ },
2239
+ });
2240
+ mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);
2241
+
2242
+ const session = await toolRouter.create(userId, {
2243
+ experimental: { customTools: [grepTool] },
2244
+ });
2245
+ await session.search({ query: 'search local text' });
2246
+
2247
+ expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(sessionId, {
2248
+ queries: [{ use_case: 'search local text' }],
2249
+ experimental: {
2250
+ custom_tools: [
2251
+ expect.objectContaining({
2252
+ slug: 'GREP',
2253
+ preload: true,
2254
+ }),
2255
+ ],
2256
+ custom_toolkits: undefined,
2257
+ },
2258
+ });
2259
+ });
2260
+
2261
it('should propagate search API errors', async () => {
2262
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2263
mockClient.toolRouter.session.search.mockRejectedValueOnce(new Error('Search failed'));
@@ -2343,10 +2437,11 @@ describe('ToolRouter', () => {
2437
expect(tools).toBe('mocked-wrapped-tools');
2438
});
2439
2346
- it('should include preloaded custom tools selected by the create response', async () => {
2440
+ it('should include custom tools with preload enabled locally', async () => {
2441
const grepTool = createCustomTool('GREP', {
2442
name: 'Grep',
2443
description: 'Search local text',
2444
+ preload: true,
2445
inputParams: z.object({
2446
pattern: z.string().describe('Pattern to search for'),
2447
}),
@@ -2355,7 +2450,7 @@ describe('ToolRouter', () => {
2450
2451
mockClient.toolRouter.session.create.mockResolvedValueOnce({
2452
...mockSessionCreateResponse,
2358
- tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'server_grep'],
2453
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
2454
experimental: {
2455
custom_tools: [
2456
{
@@ -2385,7 +2480,7 @@ describe('ToolRouter', () => {
2480
expect(tools).toBe('mocked-custom-tools');
2481
});
2482
2388
- it('should not expose custom tools unless the backend preloaded them', async () => {
2483
+ it('should not expose custom tools unless SDK preload selects them', async () => {
2484
const grepTool = createCustomTool('GREP', {
2485
name: 'Grep',
2486
description: 'Search local text',
@@ -2411,7 +2506,6 @@ describe('ToolRouter', () => {
2506
mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
2507
2508
const session = await toolRouter.create(userId, {
2414
- preload: { tools: 'all' },
2509
experimental: { customTools: [grepTool] },
2510
});
2511
await session.tools();
@@ -2420,6 +2514,41 @@ describe('ToolRouter', () => {
2514
expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);
2515
});
2516
2517
+ it('should expose custom tools by default for preload all', async () => {
2518
+ const grepTool = createCustomTool('GREP', {
2519
+ name: 'Grep',
2520
+ description: 'Search local text',
2521
+ inputParams: z.object({
2522
+ pattern: z.string(),
2523
+ }),
2524
+ execute: vi.fn(async () => ({ matches: [] })),
2525
+ });
2526
+
2527
+ mockClient.toolRouter.session.create.mockResolvedValueOnce({
2528
+ ...mockSessionCreateResponse,
2529
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
2530
+ experimental: {
2531
+ custom_tools: [
2532
+ {
2533
+ slug: 'LOCAL_GREP',
2534
+ original_slug: 'GREP',
2535
+ extends_toolkit: null,
2536
+ },
2537
+ ],
2538
+ },
2539
+ });
2540
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
2541
+
2542
+ const session = await toolRouter.create(userId, {
2543
+ preload: { tools: 'all' },
2544
+ experimental: { customTools: [grepTool] },
2545
+ });
2546
+ await session.tools();
2547
+
2548
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
2549
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
2550
+ });
2551
+
2552
it('should handle tools fetching errors', async () => {
2553
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2554