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, 21:00 UTC
Refine ToolRouter preload docs and constants
Dhawal Upadhyay committed
May 7, 2026 at 14:53 UTC
bccd32beaef05790f2d18434817588fb86f48b31
25 files changed
+689
-269
.changeset/toolrouter-direct-tools-preset.md
new
+5
@@ -0,0 +1,5 @@
1
+---
2
+'@composio/core': patch
3
+---
4
+
5
+Expose and document the Tool Router direct-tools preset via `SessionPreset.DIRECT_TOOLS`, with Python parity through `SESSION_PRESET_DIRECT_TOOLS`. Direct-tools examples now use the constants and keep the agent prompt generic while still asserting that only direct tools are exposed.
.changeset/toolrouter-preload-direct-customs.md
new
+5
@@ -0,0 +1,5 @@
1
+---
2
+'@composio/core': patch
3
+---
4
+
5
+Document and tighten Tool Router preload behavior for app tools, `preload.tools = "all"`, and SDK custom tools. Custom tool and toolkit preload hints now have clearer user-facing comments, direct custom tool descriptions now only state that search is not needed beforehand, examples assert the normalized `LOCAL_*` tool slugs exposed by `session.tools()`, and `composio.use(..., customTools/customToolkits)` reuses the same custom preload preparation path as session creation.
python/composio/__init__.py
+2
@@ -4,6 +4,7 @@ from .core.models.custom_tool_types import (
4
CustomTool,
5
SessionContext,
6
)
7
+from .core.models.tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
8
from .core.models.tool_router_session_files import RemoteFile
9
from .core.models.tools import (
10
after_execute,
@@ -35,6 +36,7 @@ __all__ = (
36
"ExperimentalToolkit",
37
"RemoteFile",
38
"SessionContext",
39
+ "SESSION_PRESET_DIRECT_TOOLS",
40
"ConnectionExpiredEvent",
41
"ConnectionState",
42
"ConnectionStatusEnum",
python/composio/core/models/__init__.py
+2
@@ -9,6 +9,7 @@ from .custom_tool_types import (
9
)
10
from .mcp import MCP
11
from .tool_router import ToolRouter
12
+from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
13
from .tool_router_session import ToolRouterSession
14
from .tool_router_session_files import RemoteFile, ToolRouterSessionFilesMount
15
from .toolkits import Toolkits
@@ -39,6 +40,7 @@ __all__ = [
40
"RegisteredCustomToolkit",
41
"RemoteFile",
42
"SessionContext",
43
+ "SESSION_PRESET_DIRECT_TOOLS",
44
"SingleConnectedAccountDetailedResponse",
45
"ToolRouter",
46
"ToolRouterSession",
python/composio/core/models/custom_tool.py
+8
-1
@@ -59,8 +59,12 @@ from .custom_tool_types import (
59
CustomToolsMapEntry,
60
CustomToolWireDefinition,
61
)
62
+from .tool_router_constants import PRELOAD_TOOLS_ALL
63
64
if t.TYPE_CHECKING:
65
+ from composio_client.types.tool_router.session_attach_response import (
66
+ Experimental as SessionAttachResponseExperimental,
67
+ )
68
from composio_client.types.tool_router.session_create_response import (
69
Experimental as SessionCreateResponseExperimental,
70
)
@@ -728,6 +732,7 @@ def build_custom_tools_map_from_response(
732
toolkits: t.Optional[t.List[ExperimentalToolkit]],
733
experimental: t.Optional[
734
t.Union[
735
+ "SessionAttachResponseExperimental",
736
"SessionCreateResponseExperimental",
737
"SessionRetrieveResponseExperimental",
738
]
@@ -804,7 +809,7 @@ def assert_no_custom_tool_slugs_in_preload(
809
custom_tools_map: t.Optional[CustomToolsMap],
810
) -> None:
811
"""Reject legacy top-level preload of custom tool slugs."""
807
- if preload_tools is None or preload_tools == "all":
812
+ if preload_tools is None or preload_tools == PRELOAD_TOOLS_ALL:
813
return
814
if isinstance(preload_tools, str):
815
raise ValidationError(
@@ -817,6 +822,8 @@ def assert_no_custom_tool_slugs_in_preload(
822
for slug in preload_tools:
823
normalized = slug.upper()
824
if normalized.startswith(LOCAL_TOOL_PREFIX) or (
825
+ # Top-level preload.tools is only for Composio-managed tool slugs.
826
+ # Custom tools use preload=True on their SDK definitions instead.
827
custom_tools_map is not None
828
and (
829
normalized in custom_tools_map.by_original_slug
python/composio/core/models/custom_tool_types.py
+17
-10
@@ -10,6 +10,7 @@ import typing as t
10
from dataclasses import dataclass, field
11
12
import typing_extensions as te
13
+from composio_client.types.tool_router import session_create_params
14
from pydantic import BaseModel
15
16
from composio_client.types.tool_router.session_execute_response import (
@@ -109,21 +110,27 @@ class CustomTool:
110
preload: t.Optional[bool] = None
111
112
112
-class CustomToolWireDefinition(te.TypedDict, total=False):
113
- slug: te.Required[str]
114
- name: te.Required[str]
115
- description: te.Required[str]
116
- input_schema: te.Required[t.Dict[str, t.Any]]
117
- extends_toolkit: str
118
- output_schema: t.Dict[str, t.Any]
113
+class CustomToolWireDefinition(
114
+ session_create_params.ExperimentalCustomTool,
115
+ total=False,
116
+):
117
+ preload: bool
118
+
119
+
120
+class CustomToolkitToolWireDefinition(
121
+ session_create_params.ExperimentalCustomToolkitTool,
122
+ total=False,
123
+):
124
preload: bool
125
126
127
class CustomToolkitWireDefinition(te.TypedDict, total=False):
123
- slug: te.Required[str]
124
- name: te.Required[str]
128
+ # Stainless 1.37.0 lacks the input-only SDK preload hint on custom
129
+ # toolkits, so this mirrors the generated shape and adds that single field.
130
description: te.Required[str]
126
- tools: te.Required[t.List[CustomToolWireDefinition]]
131
+ name: te.Required[str]
132
+ slug: te.Required[str]
133
+ tools: te.Required[t.Iterable[CustomToolkitToolWireDefinition]]
134
preload: bool
135
136
python/composio/core/models/inline_custom_tools_payload.py
+15
-4
@@ -4,6 +4,7 @@ import typing as t
4
5
from composio_client import Omit, omit
6
from composio_client.types.tool_router import (
7
+ session_attach_params,
8
session_execute_params,
9
session_search_params,
10
)
@@ -11,13 +12,23 @@ from composio_client.types.tool_router import (
12
from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
13
14
15
+def inline_custom_tools_attach_experimental(
16
+ payload: t.Optional[InlineCustomToolsWirePayload],
17
+) -> t.Union[session_attach_params.Experimental, Omit]:
18
+ if payload is None:
19
+ return omit
20
+ # Stainless generates endpoint-specific experimental types with the same custom
21
+ # definition shape, so this helper centralizes the structural cast.
22
+ return t.cast(session_attach_params.Experimental, payload)
23
+
24
+
25
def inline_custom_tools_execute_experimental(
26
payload: t.Optional[InlineCustomToolsWirePayload],
27
) -> t.Union[session_execute_params.Experimental, Omit]:
28
if payload is None:
29
return omit
19
- # The SDK wire payload is a structural subset of Stainless' endpoint-specific
20
- # experimental payloads, with input-only preload hints on custom definitions.
30
+ # Stainless generates endpoint-specific experimental types with the same custom
31
+ # definition shape, so this helper centralizes the structural cast.
32
return t.cast(session_execute_params.Experimental, payload)
33
34
@@ -26,6 +37,6 @@ def inline_custom_tools_search_experimental(
37
) -> t.Union[session_search_params.Experimental, Omit]:
38
if payload is None:
39
return omit
29
- # The SDK wire payload is a structural subset of Stainless' endpoint-specific
30
- # experimental payloads, with input-only preload hints on custom definitions.
40
+ # Stainless generates endpoint-specific experimental types with the same custom
41
+ # definition shape, so this helper centralizes the structural cast.
42
return t.cast(session_search_params.Experimental, payload)
python/composio/core/models/tool_router.py
+130
-82
@@ -14,6 +14,12 @@ from enum import Enum
14
import typing_extensions as te
15
from composio_client import omit
16
from composio_client.types.tool_router import session_create_params
17
+from composio_client.types.tool_router.session_attach_response import (
18
+ SessionAttachResponse,
19
+)
20
+from composio_client.types.tool_router.session_retrieve_response import (
21
+ SessionRetrieveResponse,
22
+)
23
24
from composio.client import HttpClient
25
from composio.core.models.base import Resource
@@ -31,14 +37,18 @@ from composio.core.models.custom_tool_types import (
37
CustomToolsMap,
38
InlineCustomToolsWirePayload,
39
)
34
-from composio_client.types.tool_router.session_retrieve_response import (
35
- SessionRetrieveResponse,
36
-)
40
from composio.core.models.tool_router_session import (
41
ToolRouterSession,
42
ToolRouterSessionPreloadConfig,
43
)
44
from composio.core.models.tool_router_session_files import ToolRouterSessionFilesMount
45
+from composio.core.models.tool_router_constants import (
46
+ PRELOAD_TOOLS_ALL,
47
+ SESSION_PRESET_DIRECT_TOOLS,
48
+)
49
+from composio.core.models.inline_custom_tools_payload import (
50
+ inline_custom_tools_attach_experimental,
51
+)
52
from composio.core.provider import TTool, TToolCollection
53
from composio.core.provider.base import BaseProvider
54
@@ -237,13 +247,26 @@ def _session_preload_config(
247
preload: _SessionPreloadLike,
248
) -> ToolRouterSessionPreloadConfig:
249
tools = preload.tools
240
- if tools == "all":
241
- return ToolRouterSessionPreloadConfig(tools="all")
250
+ if tools == PRELOAD_TOOLS_ALL:
251
+ return ToolRouterSessionPreloadConfig(tools=PRELOAD_TOOLS_ALL)
252
if isinstance(tools, list):
253
return ToolRouterSessionPreloadConfig(tools=t.cast(t.List[str], tools))
254
return ToolRouterSessionPreloadConfig(tools=[])
255
256
257
+def _preloads_all_custom_tools(
258
+ preload: t.Union[ToolRouterPreloadConfig, _SessionPreloadLike, None],
259
+) -> bool:
260
+ tools: t.Union[t.List[str], str, None]
261
+ if preload is None:
262
+ tools = None
263
+ elif isinstance(preload, dict):
264
+ tools = preload.get("tools")
265
+ else:
266
+ tools = preload.tools
267
+ return tools == PRELOAD_TOOLS_ALL
268
+
269
+
270
def _apply_session_preset_defaults(
271
session_preset: t.Optional[SessionPreset],
272
manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],
@@ -254,16 +277,52 @@ def _apply_session_preset_defaults(
277
t.Optional[ToolRouterWorkbenchConfig],
278
t.Optional[ToolRouterPreloadConfig],
279
]:
257
- if session_preset != "direct_tools":
280
+ if session_preset != SESSION_PRESET_DIRECT_TOOLS:
281
return manage_connections, workbench, preload
282
283
return (
284
False if manage_connections is None else manage_connections,
285
{"enable": False} if workbench is None else workbench,
263
- {"tools": "all"} if preload is None else preload,
286
+ {"tools": PRELOAD_TOOLS_ALL} if preload is None else preload,
287
)
288
289
290
+def _prepare_inline_custom_tools(
291
+ *,
292
+ custom_tools: t.Optional[t.List[CustomTool]],
293
+ custom_toolkits: t.Optional[t.List[ExperimentalToolkit]],
294
+ default_preload: bool = False,
295
+ preload_tools: t.Optional[t.Union[t.Sequence[str], t.Literal["all"]]] = None,
296
+) -> t.Optional[InlineCustomToolsWirePayload]:
297
+ has_customs = bool(custom_tools or custom_toolkits)
298
+ local_custom_tools_map = (
299
+ build_custom_tools_map(custom_tools or [], custom_toolkits)
300
+ if has_customs
301
+ else None
302
+ )
303
+
304
+ # Top-level preload["tools"] is for Composio-managed slugs only. Custom tools
305
+ # use their own preload flag, so reject LOCAL/custom slugs there before
306
+ # serializing the inline custom definitions.
307
+ assert_no_custom_tool_slugs_in_preload(preload_tools, local_custom_tools_map)
308
+
309
+ inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None
310
+ if has_customs:
311
+ inline_custom_tools_payload = InlineCustomToolsWirePayload()
312
+ if custom_tools:
313
+ inline_custom_tools_payload["custom_tools"] = serialize_custom_tools(
314
+ custom_tools,
315
+ default_preload=default_preload,
316
+ )
317
+ if custom_toolkits:
318
+ inline_custom_tools_payload["custom_toolkits"] = serialize_custom_toolkits(
319
+ custom_toolkits,
320
+ default_preload=default_preload,
321
+ )
322
+
323
+ return inline_custom_tools_payload
324
+
325
+
326
class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):
327
"""Configuration for assistive prompt generation.
328
@@ -631,14 +690,12 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
690
tool allowed by positive session filters such as toolkits,
691
tools, or tags; the backend validates and caps the final set.
692
Example: {'tools': ['GMAIL_FETCH_EMAILS']}
634
- :param session_preset: Optional session preset. 'direct_tools' exposes all tools
635
- allowed by the session filters directly in session.tools()
636
- and the MCP tool list, and disables meta tools by default
637
- (search, multi-execute, manage-connections, and workbench).
638
- Use when all needed tools are known upfront and helper/meta
639
- tools are not needed. Without this preset, ToolRouter uses
640
- the default configuration with meta tools enabled. Loading
641
- many tools can increase model context usage.
693
+ :param session_preset: Optional session preset. Use
694
+ SESSION_PRESET_DIRECT_TOOLS when all needed tools are
695
+ known upfront and should be exposed directly from
696
+ session.tools() and the MCP tool list. It disables
697
+ meta/helper tools by default; explicit overrides still win.
698
+ Loading many tools can increase model context usage.
699
:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).
700
Note: These features are experimental and may change.
701
Dict with:
@@ -663,6 +720,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
720
toolkits=['github', 'slack']
721
)
722
723
+ # Create a direct-tools session when all needed tools are known upfront
724
+ session = tool_router.create(
725
+ user_id='user_123',
726
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
727
+ toolkits=['github']
728
+ )
729
+
730
# Create a session with per-toolkit tool configuration
731
session = tool_router.create(
732
user_id='user_123',
@@ -731,18 +795,14 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
795
```
796
"""
797
734
- direct_tools_preset = session_preset == "direct_tools"
798
+ direct_tools_preset = session_preset == SESSION_PRESET_DIRECT_TOOLS
799
manage_connections, workbench, preload = _apply_session_preset_defaults(
800
session_preset=session_preset,
801
manage_connections=manage_connections,
802
workbench=workbench,
803
preload=preload,
804
)
741
- default_custom_preload = preload is not None and preload.get("tools") == "all"
742
- assert_no_custom_tool_slugs_in_preload(
743
- preload.get("tools") if preload is not None else None,
744
- None,
745
- )
805
+ default_custom_preload = _preloads_all_custom_tools(preload)
806
807
# Parse manage_connections config
808
manage_connections = (
@@ -884,12 +944,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
944
# experimental.assistive_prompt_config.user_timezone
945
custom_tools: t.Optional[t.List[CustomTool]] = None
946
custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None
887
- local_custom_tools_map: t.Optional[CustomToolsMap] = None
947
inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None
948
+ experimental_payload: t.Dict[str, t.Any] = {}
949
950
if experimental is not None:
891
- experimental_payload: t.Dict[str, t.Any] = {}
892
-
951
assistive_prompt_config = experimental.get("assistive_prompt")
952
if assistive_prompt_config is not None:
953
user_timezone = assistive_prompt_config.get("user_timezone")
@@ -901,43 +959,25 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
959
# Serialize custom tools and toolkits for the backend
960
custom_tools = experimental.get("custom_tools")
961
custom_toolkits = experimental.get("custom_toolkits")
904
- if custom_tools or custom_toolkits:
905
- local_custom_tools_map = build_custom_tools_map(
906
- custom_tools or [],
907
- custom_toolkits,
908
- )
909
- assert_no_custom_tool_slugs_in_preload(
910
- preload.get("tools") if preload is not None else None,
911
- local_custom_tools_map,
912
- )
962
914
- if custom_tools:
915
- experimental_payload["custom_tools"] = serialize_custom_tools(
916
- custom_tools,
917
- default_preload=default_custom_preload,
918
- )
919
- if custom_toolkits:
920
- experimental_payload["custom_toolkits"] = serialize_custom_toolkits(
921
- custom_toolkits,
922
- default_preload=default_custom_preload,
923
- )
963
+ inline_custom_tools_payload = _prepare_inline_custom_tools(
964
+ custom_tools=custom_tools,
965
+ custom_toolkits=custom_toolkits,
966
+ default_preload=default_custom_preload,
967
+ preload_tools=preload.get("tools") if preload is not None else None,
968
+ )
969
+ if inline_custom_tools_payload:
970
+ if "custom_tools" in inline_custom_tools_payload:
971
+ experimental_payload["custom_tools"] = inline_custom_tools_payload[
972
+ "custom_tools"
973
+ ]
974
+ if "custom_toolkits" in inline_custom_tools_payload:
975
+ experimental_payload["custom_toolkits"] = inline_custom_tools_payload[
976
+ "custom_toolkits"
977
+ ]
978
925
- if (
926
- "custom_tools" in experimental_payload
927
- or "custom_toolkits" in experimental_payload
928
- ):
929
- inline_custom_tools_payload = {}
930
- if "custom_tools" in experimental_payload:
931
- inline_custom_tools_payload["custom_tools"] = experimental_payload[
932
- "custom_tools"
933
- ]
934
- if "custom_toolkits" in experimental_payload:
935
- inline_custom_tools_payload["custom_toolkits"] = (
936
- experimental_payload["custom_toolkits"]
937
- )
938
-
939
- if experimental_payload:
940
- create_params["experimental"] = experimental_payload
979
+ if experimental_payload:
980
+ create_params["experimental"] = experimental_payload
981
982
if self._provider is None:
983
raise ValueError(
@@ -1035,31 +1075,37 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1075
)
1076
1077
has_customs = bool(custom_tools or custom_toolkits)
1038
- inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None
1078
+ attach_inline_custom_tools_payload = _prepare_inline_custom_tools(
1079
+ custom_tools=custom_tools,
1080
+ custom_toolkits=custom_toolkits,
1081
+ )
1082
+ inline_custom_tools_payload = attach_inline_custom_tools_payload
1083
1084
+ session: t.Union[SessionAttachResponse, SessionRetrieveResponse]
1085
if has_customs:
1041
- inline_custom_tools_payload = InlineCustomToolsWirePayload()
1042
- if custom_tools:
1043
- inline_custom_tools_payload["custom_tools"] = serialize_custom_tools(
1044
- custom_tools
1045
- )
1046
- if custom_toolkits:
1047
- inline_custom_tools_payload["custom_toolkits"] = (
1048
- serialize_custom_toolkits(custom_toolkits)
1049
- )
1050
-
1051
- from urllib.parse import quote
1052
-
1053
- body = (
1054
- {"experimental": inline_custom_tools_payload}
1055
- if inline_custom_tools_payload is not None
1056
- else {}
1057
- )
1058
- session = self._client.post(
1059
- f"/api/v3.1/tool_router/session/{quote(session_id, safe='')}/attach",
1060
- body=body,
1061
- cast_to=SessionRetrieveResponse,
1062
- )
1086
+ session = self._client.tool_router.session.attach(
1087
+ session_id,
1088
+ experimental=inline_custom_tools_attach_experimental(
1089
+ attach_inline_custom_tools_payload
1090
+ ),
1091
+ )
1092
+ else:
1093
+ session = self._client.tool_router.session.retrieve(session_id)
1094
+
1095
+ # For use(..., custom_tools=...), we only learn the existing session's
1096
+ # top-level preload config after attach returns. If that existing config
1097
+ # is preload.tools = "all", custom tools should follow the same
1098
+ # SDK-local direct exposure rule.
1099
+ default_custom_preload = _preloads_all_custom_tools(session.config.preload)
1100
+ if has_customs and default_custom_preload:
1101
+ # Attach already happened above with the caller's explicit custom
1102
+ # preload hints. This rebuild only changes the payload stored on
1103
+ # ToolRouterSession and reused by future search/execute calls.
1104
+ inline_custom_tools_payload = _prepare_inline_custom_tools(
1105
+ custom_tools=custom_tools,
1106
+ custom_toolkits=custom_toolkits,
1107
+ default_preload=True,
1108
+ )
1109
1110
custom_tools_map: t.Optional[CustomToolsMap] = None
1111
user_id: t.Optional[str] = None
@@ -1073,6 +1119,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1119
1120
preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(
1121
custom_tools_map,
1122
+ default_preload=default_custom_preload,
1123
)
1124
1125
files_mount = ToolRouterSessionFilesMount(self._client, session.session_id)
@@ -1119,6 +1166,7 @@ __all__ = [
1166
"ToolRouterWorkbenchConfig",
1167
"SandboxSize",
1168
"SessionPreset",
1169
+ "SESSION_PRESET_DIRECT_TOOLS",
1170
"ToolRouterMultiAccountConfig",
1171
"ToolRouterPreloadConfig",
1172
"ToolRouterExperimentalConfig",
python/composio/core/models/tool_router_constants.py
new
+4
@@ -0,0 +1,4 @@
1
+import typing as t
2
+
3
+SESSION_PRESET_DIRECT_TOOLS: t.Literal["direct_tools"] = "direct_tools"
4
+PRELOAD_TOOLS_ALL: t.Literal["all"] = "all"
python/composio/core/models/tool_router_session.py
+1
-1
@@ -63,7 +63,7 @@ if t.TYPE_CHECKING:
63
64
COMPOSIO_MULTI_EXECUTE_TOOL = "COMPOSIO_MULTI_EXECUTE_TOOL"
65
DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX = (
66
- "[Direct tool - call directly, no search or connection check needed beforehand.]"
66
+ "[Direct tool - call directly, no search needed beforehand.]"
67
)
68
MAX_PARALLEL_WORKERS = 5
69
python/examples/tool_router/direct_tools_preset.py
+45
-11
@@ -1,10 +1,9 @@
1
"""
2
Tool Router direct_tools session preset with OpenAI Agents.
3
4
-session_preset="direct_tools" is a shortcut for sessions where the full allowed
5
-tool set is known upfront. It disables Tool Router meta/helper tools by default
6
-and loads all tools allowed by the filters directly into session.tools() and the
7
-MCP tool list.
4
+SESSION_PRESET_DIRECT_TOOLS is a shortcut for sessions where the full allowed
5
+tool set is known upfront. It loads all tools allowed by the filters directly
6
+into session.tools() and the MCP tool list.
7
8
Usage:
9
COMPOSIO_API_KEY=... OPENAI_API_KEY=... python examples/tool_router/direct_tools_preset.py
@@ -14,8 +13,9 @@ import os
13
14
from agents import Agent, Runner
15
from composio_openai_agents import OpenAIAgentsProvider
16
+from pydantic import BaseModel, Field
17
18
-from composio import Composio
18
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
19
20
21
def require_env(name: str) -> str:
@@ -32,30 +32,64 @@ composio = Composio(
32
)
33
require_env("OPENAI_API_KEY")
34
35
+
36
+class UserNoteInput(BaseModel):
37
+ username: str = Field(description="Hacker News username, for example pg")
38
+
39
+
40
+hn_research = composio.experimental.Toolkit(
41
+ slug="HN_RESEARCH",
42
+ name="Hacker News research",
43
+ description="Internal research notes for Hacker News users.",
44
+)
45
+
46
+
47
+@hn_research.tool(
48
+ slug="GET_USER_NOTE",
49
+ name="Get Hacker News user note",
50
+ description="Return an internal research note for a Hacker News username.",
51
+)
52
+def get_user_note(input: UserNoteInput, ctx):
53
+ username = input.username.lower()
54
+ return {
55
+ "username": input.username,
56
+ "note": (
57
+ "Paul Graham; YC co-founder and essayist."
58
+ if username == "pg"
59
+ else f"No curated internal note for {input.username}."
60
+ ),
61
+ }
62
+
63
+
64
session = composio.create(
65
user_id="direct-tools-example-user",
37
- session_preset="direct_tools",
66
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
67
toolkits=["hackernews"],
68
tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},
69
+ experimental={
70
+ "custom_toolkits": [hn_research],
71
+ },
72
)
73
74
tools = session.tools()
75
+tool_names = [tool.name for tool in tools]
76
+assert "HACKERNEWS_GET_USER" in tool_names
77
+assert "LOCAL_HN_RESEARCH_GET_USER_NOTE" in tool_names
78
+assert "COMPOSIO_SEARCH_TOOLS" not in tool_names
79
+
80
print("Direct tools exposed to the agent:")
81
for tool in tools:
82
print(f"- {tool.name}")
83
84
agent = Agent(
85
name="Direct Tools Demo Agent",
49
- instructions=(
50
- "Use the provided direct tools. The session is configured without Tool "
51
- "Router meta/helper tools."
52
- ),
86
+ instructions="Use the provided tools to perform the task.",
87
model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
88
tools=tools,
89
)
90
91
result = Runner.run_sync(
92
agent,
59
- 'Use the Hacker News tool to look up user "pg" and report their karma.',
93
+ 'Look up user "pg" on Hacker News and include any internal research note.',
94
)
95
print(result.final_output)
python/examples/tool_router/preload.py
+8
-4
@@ -144,16 +144,20 @@ session = composio.create(
144
)
145
146
tools = session.tools()
147
+tool_names = [tool.name for tool in tools]
148
+assert "HACKERNEWS_GET_USER" in tool_names
149
+assert "LOCAL_LOOKUP_INTERNAL_USER" in tool_names
150
+assert "LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH" in tool_names
151
+assert "LOCAL_SEARCH_INTERNAL_USERS" not in tool_names
152
+assert "LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG" not in tool_names
153
+
154
print("Direct tools exposed to the agent:")
155
for tool in tools:
156
print(f"- {tool.name}")
157
158
agent = Agent(
159
name="Preload Demo Agent",
153
- instructions=(
154
- "Use the provided direct tools. Do not search for tools first; the "
155
- "needed tools are already loaded."
156
- ),
160
+ instructions="Use the provided tools to perform the task.",
161
model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),
162
tools=tools,
163
)
python/tests/test_tool_router.py
+140
-35
@@ -5,13 +5,11 @@ from unittest.mock import MagicMock, patch
5
import pytest
6
from composio_client import omit
7
from pydantic import BaseModel, Field
8
-from composio_client.types.tool_router.session_retrieve_response import (
9
- SessionRetrieveResponse,
10
-)
8
9
from composio.exceptions import ValidationError
10
from composio.core.models.custom_tool import ExperimentalAPI
11
from composio.core.models.tool_router import (
12
+ SESSION_PRESET_DIRECT_TOOLS,
13
ToolkitConnectionsDetails,
14
ToolkitConnectionState,
15
ToolRouter,
@@ -59,7 +57,7 @@ def mock_client():
57
58
client.tool_router.session.create.return_value = mock_session_response
59
client.tool_router.session.retrieve.return_value = mock_session_response
62
- client.post.return_value = mock_session_response
60
+ client.tool_router.session.attach.return_value = mock_session_response
61
62
# Mock link response
63
mock_link_response = MagicMock()
@@ -680,7 +678,7 @@ class TestToolRouter:
678
679
session = tool_router.create(
680
user_id="user_123",
683
- session_preset="direct_tools",
681
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
682
toolkits=["github"],
683
)
684
@@ -703,7 +701,7 @@ class TestToolRouter:
701
702
session = tool_router.create(
703
user_id="user_123",
706
- session_preset="direct_tools",
704
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
705
toolkits=["github"],
706
manage_connections=True,
707
workbench={"enable": True},
@@ -744,7 +742,7 @@ class TestToolRouter:
742
743
tool_router.create(
744
user_id="user_123",
747
- session_preset="direct_tools",
745
+ session_preset=SESSION_PRESET_DIRECT_TOOLS,
746
toolkits=["github"],
747
preload={"tools": ["GITHUB_CREATE_ISSUE"]},
748
experimental={"custom_tools": [grep]},
@@ -938,8 +936,10 @@ class TestToolRouter:
936
tool_router.use(session_id="session_123")
937
938
def test_use_session(self, tool_router, mock_client):
941
- """Test attaching an existing session."""
942
- mock_client.post.return_value.config.preload.tools = ["GMAIL_FETCH_EMAILS"]
939
+ """Test retrieving an existing session."""
940
+ mock_client.tool_router.session.retrieve.return_value.config.preload.tools = [
941
+ "GMAIL_FETCH_EMAILS"
942
+ ]
943
944
session = tool_router.use(session_id="session_123")
945
@@ -960,12 +960,9 @@ class TestToolRouter:
960
assert callable(session.toolkits)
961
assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]
962
963
- mock_client.post.assert_called_once_with(
964
- "/api/v3.1/tool_router/session/session_123/attach",
965
- body={},
966
- cast_to=SessionRetrieveResponse,
967
- )
968
- mock_client.tool_router.session.retrieve.assert_not_called()
963
+ mock_client.tool_router.session.retrieve.assert_called_once_with("session_123")
964
+ mock_client.tool_router.session.attach.assert_not_called()
965
+ mock_client.post.assert_not_called()
966
967
def test_use_session_with_custom_tools(self, tool_router, mock_client):
968
"""Test attaching custom tools when reusing a session."""
@@ -978,7 +975,7 @@ class TestToolRouter:
975
def grep(input: GrepInput, ctx):
976
return {"matches": []}
977
981
- mock_response = mock_client.post.return_value
978
+ mock_response = mock_client.tool_router.session.attach.return_value
979
mock_response.experimental = MagicMock()
980
mock_response.experimental.assistive_prompt = None
981
mock_response.experimental.custom_toolkits = []
@@ -990,18 +987,126 @@ class TestToolRouter:
987
988
session = tool_router.use(session_id="session_123", custom_tools=[grep])
989
993
- mock_client.post.assert_called_once()
994
- assert mock_client.post.call_args.args[0] == (
995
- "/api/v3.1/tool_router/session/session_123/attach"
996
- )
997
- kwargs = mock_client.post.call_args.kwargs
998
- assert kwargs["cast_to"] is SessionRetrieveResponse
999
- assert kwargs["body"]["experimental"]["custom_tools"][0]["slug"] == "GREP"
1000
- assert "custom_toolkits" not in kwargs["body"]["experimental"]
990
+ mock_client.tool_router.session.attach.assert_called_once()
991
+ kwargs = mock_client.tool_router.session.attach.call_args.kwargs
992
+ assert kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"
993
+ assert "custom_toolkits" not in kwargs["experimental"]
994
mock_client.tool_router.session.retrieve.assert_not_called()
995
+ mock_client.post.assert_not_called()
996
assert session.custom_tools()[0].slug == "SERVER_GREP"
997
assert session.custom_tools()[0].name == "Grep"
998
999
+ @patch("composio.core.models.tools.Tools")
1000
+ def test_use_session_attaches_preloaded_custom_tools(
1001
+ self,
1002
+ mock_tools_class,
1003
+ tool_router,
1004
+ mock_client,
1005
+ mock_provider,
1006
+ ):
1007
+ """use() attaches customs and exposes SDK-preloaded schemas locally."""
1008
+
1009
+ @experimental_api.tool(
1010
+ slug="GREP",
1011
+ name="Grep",
1012
+ description="Search local text",
1013
+ preload=True,
1014
+ )
1015
+ def grep(input: GrepInput, ctx):
1016
+ return {"matches": [input.pattern]}
1017
+
1018
+ attach_response = mock_client.tool_router.session.attach.return_value
1019
+ attach_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]
1020
+ attach_response.config.preload.tools = []
1021
+ attach_response.experimental = MagicMock()
1022
+ attach_response.experimental.assistive_prompt = None
1023
+ attach_response.experimental.custom_toolkits = []
1024
+ mock_custom_tool = MagicMock()
1025
+ mock_custom_tool.slug = "LOCAL_GREP"
1026
+ mock_custom_tool.original_slug = "GREP"
1027
+ mock_custom_tool.extends_toolkit = None
1028
+ attach_response.experimental.custom_tools = [mock_custom_tool]
1029
+
1030
+ mock_tools_instance = MagicMock()
1031
+ mock_tool = MagicMock()
1032
+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"
1033
+ mock_tool.toolkit.slug = "composio"
1034
+ mock_tool.input_parameters = {}
1035
+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]
1036
+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}
1037
+ mock_tools_class.return_value = mock_tools_instance
1038
+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"
1039
+
1040
+ session = tool_router.use(session_id="session_123", custom_tools=[grep])
1041
+ session.tools()
1042
+
1043
+ mock_client.tool_router.session.attach.assert_called_once()
1044
+ attach_kwargs = mock_client.tool_router.session.attach.call_args.kwargs
1045
+ assert attach_kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"
1046
+ assert attach_kwargs["experimental"]["custom_tools"][0]["preload"] is True
1047
+ mock_client.post.assert_not_called()
1048
+ mock_client.tool_router.session.retrieve.assert_not_called()
1049
+
1050
+ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]
1051
+ assert [tool.slug for tool in wrapped_tools] == [
1052
+ "COMPOSIO_SEARCH_TOOLS",
1053
+ "LOCAL_GREP",
1054
+ ]
1055
+
1056
+ @patch("composio.core.models.tools.Tools")
1057
+ def test_use_session_applies_preload_all_to_custom_tools(
1058
+ self,
1059
+ mock_tools_class,
1060
+ tool_router,
1061
+ mock_client,
1062
+ mock_provider,
1063
+ ):
1064
+ """preload.tools='all' on an existing session selects attached customs."""
1065
+
1066
+ @experimental_api.tool(
1067
+ slug="GREP",
1068
+ name="Grep",
1069
+ description="Search local text",
1070
+ )
1071
+ def grep(input: GrepInput, ctx):
1072
+ return {"matches": [input.pattern]}
1073
+
1074
+ attach_response = mock_client.tool_router.session.attach.return_value
1075
+ attach_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]
1076
+ attach_response.config.preload.tools = "all"
1077
+ attach_response.experimental = MagicMock()
1078
+ attach_response.experimental.assistive_prompt = None
1079
+ attach_response.experimental.custom_toolkits = []
1080
+ mock_custom_tool = MagicMock()
1081
+ mock_custom_tool.slug = "LOCAL_GREP"
1082
+ mock_custom_tool.original_slug = "GREP"
1083
+ mock_custom_tool.extends_toolkit = None
1084
+ attach_response.experimental.custom_tools = [mock_custom_tool]
1085
+
1086
+ mock_tools_instance = MagicMock()
1087
+ mock_tool = MagicMock()
1088
+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"
1089
+ mock_tool.toolkit.slug = "composio"
1090
+ mock_tool.input_parameters = {}
1091
+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]
1092
+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}
1093
+ mock_tools_class.return_value = mock_tools_instance
1094
+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"
1095
+
1096
+ session = tool_router.use(session_id="session_123", custom_tools=[grep])
1097
+ session.tools()
1098
+ session.search(query="search local text")
1099
+
1100
+ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]
1101
+ assert [tool.slug for tool in wrapped_tools] == [
1102
+ "COMPOSIO_SEARCH_TOOLS",
1103
+ "LOCAL_GREP",
1104
+ ]
1105
+ mock_client.tool_router.session.search.assert_called_once()
1106
+ search_kwargs = mock_client.tool_router.session.search.call_args.kwargs
1107
+ assert search_kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"
1108
+ assert search_kwargs["experimental"]["custom_tools"][0]["preload"] is True
1109
+
1110
def test_use_session_with_different_user(self, tool_router, mock_client):
1111
"""Test that use() extracts user_id from session config."""
1112
mock_attach_response = MagicMock()
@@ -1016,7 +1121,7 @@ class TestToolRouter:
1121
mock_attach_response.config.preload.tools = []
1122
mock_attach_response.experimental = None
1123
1019
- mock_client.post.return_value = mock_attach_response
1124
+ mock_client.tool_router.session.retrieve.return_value = mock_attach_response
1125
1126
session = tool_router.use(session_id="session_456")
1127
@@ -1024,8 +1129,10 @@ class TestToolRouter:
1129
assert session.mcp.type == ToolRouterMCPServerType.HTTP
1130
1131
def test_use_session_throws_error_on_failure(self, tool_router, mock_client):
1027
- """Test that use() throws error if attach fails."""
1028
- mock_client.post.side_effect = Exception("Session not found")
1132
+ """Test that use() throws error if retrieve fails."""
1133
+ mock_client.tool_router.session.retrieve.side_effect = Exception(
1134
+ "Session not found"
1135
+ )
1136
1137
with pytest.raises(Exception, match="Session not found"):
1138
tool_router.use(session_id="invalid_session")
@@ -1440,7 +1547,7 @@ class TestToolRouter:
1547
mock_attach_response.experimental = None
1548
1549
mock_client.tool_router.session.create.return_value = mock_create_response
1443
- mock_client.post.return_value = mock_attach_response
1550
+ mock_client.tool_router.session.retrieve.return_value = mock_attach_response
1551
1552
# Create a new session
1553
created_session = tool_router.create(user_id="user_123")
@@ -1452,12 +1559,10 @@ class TestToolRouter:
1559
1560
# Verify both methods were called
1561
mock_client.tool_router.session.create.assert_called_once()
1455
- mock_client.post.assert_called_once_with(
1456
- "/api/v3.1/tool_router/session/retrieved_session/attach",
1457
- body={},
1458
- cast_to=SessionRetrieveResponse,
1562
+ mock_client.tool_router.session.retrieve.assert_called_once_with(
1563
+ "retrieved_session"
1564
)
1460
- mock_client.tool_router.session.retrieve.assert_not_called()
1565
+ mock_client.post.assert_not_called()
1566
1567
1568
class TestToolRouterTypes:
@@ -1811,8 +1916,8 @@ class TestToolRouterIntegration:
1916
created_session = tool_router.create(user_id="user_123")
1917
created_session_id = created_session.session_id
1918
1814
- # Setup attach to return the same session
1815
- mock_client.post.return_value = (
1919
+ # Setup retrieve to return the same session
1920
+ mock_client.tool_router.session.retrieve.return_value = (
1921
mock_client.tool_router.session.create.return_value
1922
)
1923
ts/examples/tool-router/README.md
+4
-1
@@ -5,11 +5,13 @@ This example demonstrates how to use Composio SDK for tool-router.
5
## Setup
6
7
1. **Install dependencies:**
8
+
9
```bash
10
pnpm install
11
```
12
13
2. **Configure environment:**
14
+
15
```bash
16
cp .env.example .env
17
```
@@ -41,11 +43,12 @@ pnpm direct-tools
43
- Fetches available tools
44
- Demonstrates basic usage patterns
45
- Shows how to preload selected app tools and SDK-local custom tools into `session.tools()`
44
-- Shows `sessionPreset: "direct_tools"` for loading all tools allowed by session filters without meta/helper tools
46
+- Shows `SessionPreset.DIRECT_TOOLS` for loading all tools allowed by session filters without meta/helper tools
47
48
## Customization
49
50
Edit `src/index.ts` to:
51
+
52
- Add specific apps you want to integrate with
53
- Implement your business logic
54
- Add error handling and logging
ts/examples/tool-router/src/direct-tools-preset.ts
+41
-6
@@ -1,7 +1,7 @@
1
/**
2
* Tool Router direct_tools session preset with OpenAI Agents
3
*
4
- * `sessionPreset: "direct_tools"` is a shortcut for sessions where the full
4
+ * `sessionPreset: SessionPreset.DIRECT_TOOLS` is a shortcut for sessions where the full
5
* allowed tool set is known upfront. It disables Tool Router meta/helper tools
6
* by default and loads all tools allowed by the filters directly into
7
* `session.tools()` and the MCP tool list.
@@ -10,9 +10,16 @@
10
* COMPOSIO_API_KEY=... OPENAI_API_KEY=... bun src/direct-tools-preset.ts
11
*/
12
import 'dotenv/config';
13
-import { Composio } from '@composio/core';
13
+import assert from 'node:assert/strict';
14
+import {
15
+ Composio,
16
+ SessionPreset,
17
+ experimental_createTool,
18
+ experimental_createToolkit,
19
+} from '@composio/core';
20
import { OpenAIAgentsProvider } from '@composio/openai-agents';
21
import { Agent, run } from '@openai/agents';
22
+import { z } from 'zod/v3';
23
24
function requireEnv(name: 'COMPOSIO_API_KEY' | 'OPENAI_API_KEY'): string {
25
const value = process.env[name];
@@ -31,17 +38,46 @@ const composio = new Composio({
38
provider: new OpenAIAgentsProvider(),
39
});
40
41
+const getUserNote = experimental_createTool('GET_USER_NOTE', {
42
+ name: 'Get Hacker News user note',
43
+ description: 'Return an internal research note for a Hacker News username.',
44
+ inputParams: z.object({
45
+ username: z.string().describe('Hacker News username, for example pg'),
46
+ }),
47
+ execute: async ({ username }) => ({
48
+ username,
49
+ note:
50
+ username.toLowerCase() === 'pg'
51
+ ? 'Paul Graham; YC co-founder and essayist.'
52
+ : `No curated internal note for ${username}.`,
53
+ }),
54
+});
55
+
56
+const hnResearch = experimental_createToolkit('HN_RESEARCH', {
57
+ name: 'Hacker News research',
58
+ description: 'Internal research notes for Hacker News users.',
59
+ tools: [getUserNote],
60
+});
61
+
62
const session = await composio.create('direct-tools-example-user', {
35
- sessionPreset: 'direct_tools',
63
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
64
toolkits: ['hackernews'],
65
tools: {
66
hackernews: {
67
enable: ['HACKERNEWS_GET_USER'],
68
},
69
},
70
+ experimental: {
71
+ customToolkits: [hnResearch],
72
+ },
73
});
74
75
const tools = await session.tools();
76
+const toolNames = tools.map(tool => tool.name);
77
+assert(toolNames.includes('HACKERNEWS_GET_USER'));
78
+assert(toolNames.includes('LOCAL_HN_RESEARCH_GET_USER_NOTE'));
79
+assert(!toolNames.includes('COMPOSIO_SEARCH_TOOLS'));
80
+
81
console.log('Direct tools exposed to the agent:');
82
for (const tool of tools) {
83
console.log(`- ${tool.name}`);
@@ -49,15 +85,14 @@ for (const tool of tools) {
85
86
const agent = new Agent({
87
name: 'Direct Tools Demo Agent',
52
- instructions:
53
- 'Use the provided direct tools. The session is configured without Tool Router meta/helper tools.',
88
+ instructions: 'Use the provided tools to perform the task.',
89
model: process.env.OPENAI_MODEL ?? 'gpt-5.5',
90
tools,
91
});
92
93
const prompt =
94
process.argv.slice(2).join(' ') ||
60
- 'Use the Hacker News tool to look up user "pg" and report their karma.';
95
+ 'Look up user "pg" on Hacker News and include any internal research note.';
96
97
console.log(`\nUser: ${prompt}\n`);
98
const result = await run(agent, prompt);
ts/examples/tool-router/src/preload.ts
+9
-2
@@ -9,6 +9,7 @@
9
* COMPOSIO_API_KEY=... OPENAI_API_KEY=... bun src/preload.ts
10
*/
11
import 'dotenv/config';
12
+import assert from 'node:assert/strict';
13
import { Composio, experimental_createTool, experimental_createToolkit } from '@composio/core';
14
import { OpenAIAgentsProvider } from '@composio/openai-agents';
15
import { Agent, run } from '@openai/agents';
@@ -129,6 +130,13 @@ const session = await composio.create('preload-example-user', {
130
});
131
132
const tools = await session.tools();
133
+const toolNames = tools.map(tool => tool.name);
134
+assert(toolNames.includes('HACKERNEWS_GET_USER'));
135
+assert(toolNames.includes('LOCAL_LOOKUP_INTERNAL_USER'));
136
+assert(toolNames.includes('LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH'));
137
+assert(!toolNames.includes('LOCAL_SEARCH_INTERNAL_USERS'));
138
+assert(!toolNames.includes('LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG'));
139
+
140
console.log('Direct tools exposed to the agent:');
141
for (const tool of tools) {
142
console.log(`- ${tool.name}`);
@@ -136,8 +144,7 @@ for (const tool of tools) {
144
145
const agent = new Agent({
146
name: 'Preload Demo Agent',
139
- instructions:
140
- 'Use the provided direct tools. Do not search for tools first; the needed tools are already loaded.',
147
+ instructions: 'Use the provided tools to perform the task.',
148
model: process.env.OPENAI_MODEL ?? 'gpt-5.5',
149
tools,
150
});
ts/packages/core/src/composio.ts
+2
@@ -203,6 +203,8 @@ export class Composio<
203
toolRouter: ToolRouter<unknown, unknown, TProvider>;
204
/**
205
* Creates a new tool router session for a user.
206
+ * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools
207
+ * should be exposed directly; see `ToolRouterCreateSessionConfig`.
208
*
209
* @param userId {string} The user id to create the session for
210
* @param config {ToolRouterConfig} The config for the tool router session
ts/packages/core/src/lib/toolRouterConstants.ts
new
+1
@@ -0,0 +1 @@
1
+export const PRELOAD_TOOLS_ALL = 'all' as const;
ts/packages/core/src/models/CustomTool.ts
+5
-2
@@ -41,6 +41,7 @@ import type {
41
SessionRetrieveResponse,
42
} from '@composio/client/resources/tool-router/session/session.mjs';
43
import { ValidationError } from '../errors';
44
+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
45
46
/** Prefix applied by the backend to local tool slugs for disambiguation. */
47
export const LOCAL_TOOL_PREFIX = 'LOCAL_';
@@ -519,16 +520,18 @@ export function findCustomToolMapEntryByFinalSlug(
520
* @internal
521
*/
522
export function assertNoCustomToolSlugsInPreload(
522
- preloadTools: readonly string[] | 'all' | undefined,
523
+ preloadTools: readonly string[] | typeof PRELOAD_TOOLS_ALL | undefined,
524
customToolsMap: CustomToolsMap | undefined
525
): void {
525
- if (!preloadTools || preloadTools === 'all') {
526
+ if (!preloadTools || preloadTools === PRELOAD_TOOLS_ALL) {
527
return;
528
}
529
530
const customPreloadSlugs = preloadTools.filter(slug => {
531
const normalized = slug.toUpperCase();
532
return (
533
+ // Top-level preload.tools is only for Composio-managed tool slugs.
534
+ // Custom tools use `preload: true` on their SDK definitions instead.
535
normalized.startsWith(LOCAL_TOOL_PREFIX) ||
536
customToolsMap?.byOriginalSlug.has(normalized) ||
537
customToolsMap?.byFinalSlug.has(normalized)
ts/packages/core/src/models/ToolRouter.ts
+87
-53
@@ -28,9 +28,11 @@ import {
28
MCPServerType,
29
ToolRouterMCPServerConfig,
30
ToolRouterSessionMetadata,
31
+ SessionPreset,
32
} from '../types/toolRouter.types';
33
import { ToolRouterCreateSessionConfigSchema } from '../types/toolRouter.types';
34
import {
35
+ SessionAttachResponse,
36
SessionCreateParams,
37
SessionCreateResponse,
38
SessionRetrieveResponse,
@@ -48,6 +50,7 @@ import {
50
transformToolRouterToolkitsParams,
51
transformToolRouterMultiAccountParams,
52
} from '../lib/toolRouterParams';
53
+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
54
import { ToolRouterSession } from './ToolRouterSession';
55
import {
56
assertNoCustomToolSlugsInPreload,
@@ -59,7 +62,9 @@ import {
62
} from './CustomTool';
63
import type { CustomToolsMap } from '../types/customTool.types';
64
62
-function getSessionMetadata(session: SessionCreateResponse | SessionRetrieveResponse) {
65
+function getSessionMetadata(
66
+ session: SessionCreateResponse | SessionRetrieveResponse | SessionAttachResponse
67
+) {
68
const metadata: ToolRouterSessionMetadata = {
69
preload: session.config.preload,
70
configVersion: session.config_version,
@@ -68,6 +73,45 @@ function getSessionMetadata(session: SessionCreateResponse | SessionRetrieveResp
73
return metadata;
74
}
75
76
+function preloadsAllCustomTools(preload?: { tools?: readonly string[] | string }): boolean {
77
+ return preload?.tools === PRELOAD_TOOLS_ALL;
78
+}
79
+
80
+function prepareInlineCustomTools(options: {
81
+ customTools?: CustomTool[];
82
+ customToolkits?: CustomToolkit[];
83
+ defaultPreload?: boolean;
84
+ preloadTools?: readonly string[] | typeof PRELOAD_TOOLS_ALL;
85
+}): InlineCustomToolsWirePayload | undefined {
86
+ const { customTools, customToolkits, defaultPreload = false, preloadTools } = options;
87
+ const hasCustoms = !!(customTools?.length || customToolkits?.length);
88
+ const localCustomToolsMap = hasCustoms
89
+ ? buildCustomToolsMap(customTools ?? [], customToolkits)
90
+ : undefined;
91
+
92
+ // Top-level preload.tools is for Composio-managed slugs only. Custom tools
93
+ // use their own preload flag, so reject LOCAL/custom slugs there before
94
+ // serializing the inline custom definitions.
95
+ assertNoCustomToolSlugsInPreload(preloadTools, localCustomToolsMap);
96
+
97
+ const serializedTools = customTools?.length
98
+ ? serializeCustomTools(customTools, { defaultPreload })
99
+ : undefined;
100
+ const serializedToolkits = customToolkits?.length
101
+ ? serializeCustomToolkits(customToolkits, { defaultPreload })
102
+ : undefined;
103
+
104
+ const inlineCustomToolsPayload =
105
+ serializedTools || serializedToolkits
106
+ ? {
107
+ ...(serializedTools ? { custom_tools: serializedTools } : {}),
108
+ ...(serializedToolkits ? { custom_toolkits: serializedToolkits } : {}),
109
+ }
110
+ : undefined;
111
+
112
+ return inlineCustomToolsPayload;
113
+}
114
+
115
export class ToolRouter<
116
TToolCollection,
117
TTool,
@@ -98,6 +142,8 @@ export class ToolRouter<
142
143
/**
144
* Creates a new tool router session for a user.
145
+ * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools
146
+ * should be exposed directly; see `ToolRouterCreateSessionConfig`.
147
*
148
* @param userId {string} The user id to create the session for
149
* @param config {ToolRouterCreateSessionConfig} The config for the tool router session
@@ -105,7 +151,7 @@ export class ToolRouter<
151
*
152
* @example
153
* ```typescript
108
- * import { Composio, experimental_createTool } from '@composio/core';
154
+ * import { Composio } from '@composio/core';
155
*
156
* const composio = new Composio();
157
*
@@ -117,16 +163,6 @@ export class ToolRouter<
163
* customToolkits: [myToolkit],
164
* },
165
* });
120
- *
121
- * // Custom tools are searched by default. Set `preload: true` on a custom
122
- * // tool or toolkit to expose it directly from `session.tools()`.
123
- *
124
- * // Expose all tools allowed by filters directly, without meta/helper tools.
125
- * // `preload.tools = "all"` requires a positive filter such as `toolkits`.
126
- * const directSession = await composio.create('user_123', {
127
- * sessionPreset: 'direct_tools',
128
- * toolkits: ['github'],
129
- * });
166
* ```
167
*/
168
async create(
@@ -134,17 +170,18 @@ export class ToolRouter<
170
config?: ToolRouterCreateSessionConfig
171
): Promise<Session<TToolCollection, TTool, TProvider>> {
172
const routerConfig = ToolRouterCreateSessionConfigSchema.parse(config ?? {});
137
- const isDirectToolsPreset = routerConfig.sessionPreset === 'direct_tools';
173
+ const isDirectToolsPreset = routerConfig.sessionPreset === SessionPreset.DIRECT_TOOLS;
174
175
// Extract custom tools/toolkits from experimental config
176
const customTools = routerConfig.experimental?.customTools;
177
const customToolkits = routerConfig.experimental?.customToolkits;
142
- const defaultCustomPreload = routerConfig.preload?.tools === 'all';
143
- const localCustomToolsMap =
144
- customTools?.length || customToolkits?.length
145
- ? buildCustomToolsMap(customTools ?? [], customToolkits)
146
- : undefined;
147
- assertNoCustomToolSlugsInPreload(routerConfig.preload?.tools, localCustomToolsMap);
178
+ const defaultCustomPreload = preloadsAllCustomTools(routerConfig.preload);
179
+ const inlineCustomToolsPayload = prepareInlineCustomTools({
180
+ customTools,
181
+ customToolkits,
182
+ defaultPreload: defaultCustomPreload,
183
+ preloadTools: routerConfig.preload?.tools,
184
+ });
185
186
// Build the typed experimental payload for the backend
187
const experimentalPayload: SessionCreateParams['experimental'] = {};
@@ -155,27 +192,12 @@ export class ToolRouter<
192
};
193
}
194
158
- if (customTools?.length) {
159
- experimentalPayload.custom_tools = serializeCustomTools(customTools, {
160
- defaultPreload: defaultCustomPreload,
161
- });
195
+ if (inlineCustomToolsPayload?.custom_tools) {
196
+ experimentalPayload.custom_tools = inlineCustomToolsPayload.custom_tools;
197
}
163
- if (customToolkits?.length) {
164
- experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits, {
165
- defaultPreload: defaultCustomPreload,
166
- });
198
+ if (inlineCustomToolsPayload?.custom_toolkits) {
199
+ experimentalPayload.custom_toolkits = inlineCustomToolsPayload.custom_toolkits;
200
}
168
- const inlineCustomToolsPayload =
169
- experimentalPayload.custom_tools || experimentalPayload.custom_toolkits
170
- ? {
171
- ...(experimentalPayload.custom_tools
172
- ? { custom_tools: experimentalPayload.custom_tools }
173
- : {}),
174
- ...(experimentalPayload.custom_toolkits
175
- ? { custom_toolkits: experimentalPayload.custom_toolkits }
176
- : {}),
177
- }
178
- : undefined;
201
202
const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);
203
@@ -256,24 +278,36 @@ export class ToolRouter<
278
const customToolkits = options?.customToolkits;
279
const hasCustoms = !!(customTools?.length || customToolkits?.length);
280
259
- let inlineCustomToolsPayload: InlineCustomToolsWirePayload | undefined;
281
+ let session: SessionRetrieveResponse | SessionAttachResponse;
282
+ const attachInlineCustomToolsPayload = prepareInlineCustomTools({
283
+ customTools,
284
+ customToolkits,
285
+ });
286
+ let inlineCustomToolsPayload = attachInlineCustomToolsPayload;
287
288
if (hasCustoms) {
262
- const serializedTools = customTools?.length ? serializeCustomTools(customTools) : undefined;
263
- const serializedToolkits = customToolkits?.length
264
- ? serializeCustomToolkits(customToolkits)
265
- : undefined;
266
-
267
- inlineCustomToolsPayload = {
268
- ...(serializedTools ? { custom_tools: serializedTools } : {}),
269
- ...(serializedToolkits ? { custom_toolkits: serializedToolkits } : {}),
270
- };
289
+ session = await this.client.toolRouter.session.attach(id, {
290
+ experimental: attachInlineCustomToolsPayload,
291
+ });
292
+ } else {
293
+ session = await this.client.toolRouter.session.retrieve(id);
294
}
295
273
- const session = await this.client.post<SessionRetrieveResponse>(
274
- `/api/v3.1/tool_router/session/${encodeURIComponent(id)}/attach`,
275
- { body: inlineCustomToolsPayload ? { experimental: inlineCustomToolsPayload } : {} }
276
- );
296
+ // For use(...customTools), we only learn the existing session's top-level
297
+ // preload config after attach returns. If that existing config is
298
+ // preload.tools = "all", custom tools should follow the same SDK-local
299
+ // direct exposure rule.
300
+ const defaultCustomPreload = preloadsAllCustomTools(session.config.preload);
301
+ if (hasCustoms && defaultCustomPreload) {
302
+ // Attach already happened above with the caller's explicit custom preload
303
+ // hints. This rebuild only changes the payload stored on ToolRouterSession
304
+ // and reused by future search/execute calls.
305
+ inlineCustomToolsPayload = prepareInlineCustomTools({
306
+ customTools,
307
+ customToolkits,
308
+ defaultPreload: true,
309
+ });
310
+ }
311
312
let customToolsMap: CustomToolsMap | undefined;
313
let userId: string | undefined;
@@ -288,7 +322,7 @@ export class ToolRouter<
322
323
const metadata = {
324
...getSessionMetadata(session),
291
- preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap),
325
+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),
326
inlineCustomToolsPayload,
327
};
328
ts/packages/core/src/models/ToolRouterSession.ts
+2
-2
@@ -55,7 +55,7 @@ import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';
55
56
const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';
57
export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =
58
- '[Direct tool - call directly, no search or connection check needed beforehand.]';
58
+ '[Direct tool - call directly, no search needed beforehand.]';
59
60
export class ToolRouterSession<
61
TToolCollection,
@@ -147,7 +147,7 @@ export class ToolRouterSession<
147
toolSlug,
148
input,
149
modifiers,
150
- toolBySlug.get(toolSlug.toUpperCase()),
150
+ toolBySlug.get(toolSlug.toUpperCase())
151
);
152
};
153
ts/packages/core/src/models/inlineCustomToolsPayload.ts
+2
-2
@@ -11,7 +11,7 @@ type InlineCustomToolsExperimental =
11
export function inlineCustomToolsExperimental<TExperimental extends InlineCustomToolsExperimental>(
12
payload?: InlineCustomToolsWirePayload
13
): TExperimental | undefined {
14
- // The SDK wire payload is a structural subset of Stainless' endpoint-specific
15
- // experimental payloads, with input-only preload hints on custom definitions.
14
+ // Stainless generates endpoint-specific experimental types with the same custom
15
+ // definition shape, so this helper centralizes the structural cast.
16
return payload as TExperimental | undefined;
17
}
ts/packages/core/src/types/customTool.types.ts
+8
-14
@@ -139,7 +139,7 @@ export const CreateCustomToolBaseSchema = z.object({
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 with the inline custom definition.'
142
+ 'When true, include this custom tool in session.tools() so it can be called without searching first.'
143
),
144
});
145
@@ -170,9 +170,8 @@ export interface CustomTool {
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 with the inline
175
- * custom definition.
173
+ * Include this custom tool in session.tools() so it can be called without
174
+ * searching first.
175
*/
176
readonly preload?: boolean;
177
readonly inputSchema: Record<string, unknown>;
@@ -187,9 +186,7 @@ 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
190
-export type CustomToolWireDefinition = CustomToolDefinition & {
191
- preload?: boolean;
192
-};
189
+export type CustomToolWireDefinition = CustomToolDefinition;
190
191
// ────────────────────────────────────────────────────────────────
192
// Custom toolkit types
@@ -206,7 +203,7 @@ export const CreateCustomToolkitBaseSchema = z.object({
203
.boolean()
204
.optional()
205
.describe(
209
- 'When true, expose tools in this custom toolkit directly from session.tools(). Tool-level preload values override this default.'
206
+ 'When true, include tools from this custom toolkit in session.tools(). Tool-level preload values override this default.'
207
),
208
});
209
@@ -225,7 +222,7 @@ export interface CustomToolkit {
222
readonly name: string;
223
readonly description: string;
224
/**
228
- * Default direct-exposure setting for tools in this custom toolkit.
225
+ * Default session.tools() exposure for tools in this custom toolkit.
226
* Tool-level preload values override this default.
227
*/
228
readonly preload?: boolean;
@@ -235,10 +232,7 @@ export interface CustomToolkit {
232
/** Serialized toolkit definition sent to backend. Uses official client type. */
233
export type CustomToolkitDefinition = SessionCreateParams.Experimental.CustomToolkit;
234
238
-export type CustomToolkitWireDefinition = Omit<CustomToolkitDefinition, 'tools'> & {
239
- preload?: boolean;
240
- tools: Array<CustomToolkitDefinition['tools'][number] & { preload?: boolean }>;
241
-};
235
+export type CustomToolkitWireDefinition = CustomToolkitDefinition;
236
237
export interface InlineCustomToolsWirePayload {
238
custom_tools?: CustomToolWireDefinition[];
@@ -266,7 +260,7 @@ export type CustomToolsMap = {
260
byOriginalSlug: Map<string, CustomToolsMapEntry>;
261
/** The original custom toolkits passed at session creation — used for session.customToolkits() */
262
toolkits?: CustomToolkit[];
269
- /** The original standalone custom tools passed at session creation — kept for inline re-injection on subsequent v3.1 requests. */
263
+ /** The original standalone custom tools passed at session creation — kept for inline re-injection on later requests. */
264
tools?: CustomTool[];
265
};
266
ts/packages/core/src/types/toolRouter.types.ts
+11
-5
@@ -11,6 +11,12 @@ import type {
11
RegisteredCustomTool,
12
RegisteredCustomToolkit,
13
} from './customTool.types';
14
+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
15
+
16
+export const SessionPreset = {
17
+ DIRECT_TOOLS: 'direct_tools',
18
+} as const;
19
+export type SessionPreset = (typeof SessionPreset)[keyof typeof SessionPreset];
20
21
export const MCPServerTypeSchema = z.enum(['http', 'sse']);
22
export type MCPServerType = z.infer<typeof MCPServerTypeSchema>;
@@ -173,7 +179,7 @@ export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;
179
const ToolRouterCreateSessionConfigBaseSchema = z
180
.object({
181
sessionPreset: z
176
- .literal('direct_tools')
182
+ .literal(SessionPreset.DIRECT_TOOLS)
183
.optional()
184
.describe(
185
'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.'
@@ -273,7 +279,7 @@ const ToolRouterCreateSessionConfigBaseSchema = z
279
preload: z
280
.object({
281
tools: z
276
- .union([z.array(z.string()), z.literal('all')])
282
+ .union([z.array(z.string()), z.literal(PRELOAD_TOOLS_ALL)])
283
.optional()
284
.describe(
285
'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.'
@@ -321,7 +327,7 @@ const applyDirectToolsPresetDefaults = (value: unknown): unknown => {
327
}
328
329
const config = value as Record<string, unknown>;
324
- if (config.sessionPreset !== 'direct_tools') {
330
+ if (config.sessionPreset !== SessionPreset.DIRECT_TOOLS) {
331
return value;
332
}
333
@@ -329,7 +335,7 @@ const applyDirectToolsPresetDefaults = (value: unknown): unknown => {
335
...config,
336
manageConnections: config.manageConnections === undefined ? false : config.manageConnections,
337
workbench: config.workbench === undefined ? { enable: false } : config.workbench,
332
- preload: config.preload === undefined ? { tools: 'all' } : config.preload,
338
+ preload: config.preload === undefined ? { tools: PRELOAD_TOOLS_ALL } : config.preload,
339
};
340
};
341
@@ -339,7 +345,7 @@ export const ToolRouterCreateSessionConfigSchema = z
345
/**
346
* The config for the tool router session.
347
*
342
- * @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.
348
+ * @param {SessionPreset} [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.
349
* @param {ToolRouterToolkitsParamSchema | ToolRouterToolkitsDisabledConfigSchema | ToolRouterToolkitsEnabledConfigSchema} toolkits - The toolkits to use in the tool router session
350
* @param {Record<string, ToolRouterToolsParam | ToolRouterConfigTools>} tools - The tools to configure per toolkit (key is toolkit slug)
351
* @param {Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>} tags - Global tags to filter tools by behavior
ts/packages/core/test/models/toolRouter.test.ts
+135
-34
@@ -6,7 +6,11 @@ import { telemetry } from '../../src/telemetry/Telemetry';
6
import { MockProvider } from '../utils/mocks/provider.mock';
7
import { Tools } from '../../src/models/Tools';
8
import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';
9
-import { ToolRouterCreateSessionConfig, Session } from '../../src/types/toolRouter.types';
9
+import {
10
+ ToolRouterCreateSessionConfig,
11
+ Session,
12
+ SessionPreset,
13
+} from '../../src/types/toolRouter.types';
14
import { createCustomTool } from '../../src/models/CustomTool';
15
import { DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX } from '../../src/models/ToolRouterSession';
16
@@ -36,6 +40,7 @@ const createMockClient = () => ({
40
session: {
41
create: vi.fn(),
42
retrieve: vi.fn(),
43
+ attach: vi.fn(),
44
link: vi.fn(),
45
toolkits: vi.fn(),
46
search: vi.fn(),
@@ -162,6 +167,8 @@ describe('ToolRouter', () => {
167
provider: mockProvider,
168
apiKey: 'test-api-key',
169
});
170
+ mockClient.toolRouter.session.retrieve.mockResolvedValue(mockSessionRetrieveResponse);
171
+ mockClient.toolRouter.session.attach.mockResolvedValue(mockSessionRetrieveResponse);
172
});
173
174
describe('constructor', () => {
@@ -323,7 +330,7 @@ describe('ToolRouter', () => {
330
});
331
332
const session = await toolRouter.create(userId, {
326
- sessionPreset: 'direct_tools',
333
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
334
toolkits: ['github'],
335
});
336
@@ -356,7 +363,7 @@ describe('ToolRouter', () => {
363
});
364
365
const session = await toolRouter.create(userId, {
359
- sessionPreset: 'direct_tools',
366
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
367
toolkits: ['github'],
368
manageConnections: true,
369
workbench: { enable: true },
@@ -408,7 +415,7 @@ describe('ToolRouter', () => {
415
});
416
417
await toolRouter.create(userId, {
411
- sessionPreset: 'direct_tools',
418
+ sessionPreset: SessionPreset.DIRECT_TOOLS,
419
toolkits: ['github'],
420
preload: { tools: ['GITHUB_CREATE_ISSUE'] },
421
experimental: { customTools: [grepTool] },
@@ -2919,16 +2926,15 @@ describe('ToolRouter', () => {
2926
2927
describe('use method', () => {
2928
const sessionId = 'session_123';
2922
- const attachEndpoint = (id: string) =>
2923
- `/api/v3.1/tool_router/session/${encodeURIComponent(id)}/attach`;
2929
2925
- it('should attach an existing session by ID', async () => {
2926
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
2930
+ it('should retrieve an existing session by ID', async () => {
2931
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
2932
2933
const session = await toolRouter.use(sessionId);
2934
2930
- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), { body: {} });
2931
- expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
2935
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId);
2936
+ expect(mockClient.toolRouter.session.attach).not.toHaveBeenCalled();
2937
+ expect(mockClient.post).not.toHaveBeenCalled();
2938
expect(session).toHaveProperty('sessionId', 'session_123');
2939
expect(session).toHaveProperty('mcp');
2940
expect(session.mcp).toEqual({
@@ -2953,7 +2959,7 @@ describe('ToolRouter', () => {
2959
execute: vi.fn(async () => ({ matches: [] })),
2960
});
2961
2956
- mockClient.post.mockResolvedValueOnce({
2962
+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({
2963
...mockSessionRetrieveResponse,
2964
experimental: {
2965
custom_tools: [
@@ -2968,16 +2974,15 @@ describe('ToolRouter', () => {
2974
2975
const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
2976
2971
- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), {
2972
- body: {
2973
- experimental: {
2974
- custom_tools: [expect.objectContaining({ slug: 'GREP' })],
2975
- },
2977
+ expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(sessionId, {
2978
+ experimental: {
2979
+ custom_tools: [expect.objectContaining({ slug: 'GREP' })],
2980
},
2981
});
2978
- expect(mockClient.post.mock.calls[0][1].body.experimental).not.toHaveProperty(
2982
+ expect(mockClient.toolRouter.session.attach.mock.calls[0][1].experimental).not.toHaveProperty(
2983
'custom_toolkits'
2984
);
2985
+ expect(mockClient.post).not.toHaveBeenCalled();
2986
expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
2987
expect(session.customTools()).toEqual([
2988
expect.objectContaining({
@@ -2996,7 +3001,7 @@ describe('ToolRouter', () => {
3001
},
3002
};
3003
2999
- mockClient.post.mockResolvedValueOnce(customResponse);
3004
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);
3005
3006
const session = await toolRouter.use(sessionId);
3007
@@ -3006,7 +3011,7 @@ describe('ToolRouter', () => {
3011
});
3012
3013
it('should return a session with working tools function', async () => {
3009
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
3014
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3015
3016
const session = await toolRouter.use(sessionId);
3017
@@ -3025,7 +3030,7 @@ describe('ToolRouter', () => {
3030
});
3031
3032
it('should return a session with working authorize function', async () => {
3028
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
3033
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3034
mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
3035
3036
const session = await toolRouter.use(sessionId);
@@ -3040,7 +3045,7 @@ describe('ToolRouter', () => {
3045
});
3046
3047
it('should return a session with working toolkits function', async () => {
3043
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
3048
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3049
mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
3050
3051
const session = await toolRouter.use(sessionId);
@@ -3057,6 +3062,100 @@ describe('ToolRouter', () => {
3062
expect(toolkitsResult.items[0].slug).toBe('gmail');
3063
});
3064
3065
+ it('should attach custom tools and expose SDK-preloaded custom schemas', async () => {
3066
+ const grepTool = createCustomTool('GREP', {
3067
+ name: 'Grep',
3068
+ description: 'Search local text',
3069
+ preload: true,
3070
+ inputParams: z.object({ pattern: z.string() }),
3071
+ execute: vi.fn(async () => ({ matches: [] })),
3072
+ });
3073
+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({
3074
+ ...mockSessionRetrieveResponse,
3075
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
3076
+ experimental: {
3077
+ custom_tools: [
3078
+ {
3079
+ slug: 'LOCAL_GREP',
3080
+ original_slug: 'GREP',
3081
+ extends_toolkit: null,
3082
+ },
3083
+ ],
3084
+ },
3085
+ });
3086
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3087
+
3088
+ const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
3089
+ await session.tools();
3090
+
3091
+ expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(sessionId, {
3092
+ experimental: {
3093
+ custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],
3094
+ },
3095
+ });
3096
+ expect(mockClient.post).not.toHaveBeenCalled();
3097
+ expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
3098
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
3099
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
3100
+ });
3101
+
3102
+ it('should apply preload all from an attached session to custom tools in use()', async () => {
3103
+ const grepTool = createCustomTool('GREP', {
3104
+ name: 'Grep',
3105
+ description: 'Search local text',
3106
+ inputParams: z.object({ pattern: z.string() }),
3107
+ execute: vi.fn(async () => ({ matches: [] })),
3108
+ });
3109
+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({
3110
+ ...mockSessionRetrieveResponse,
3111
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
3112
+ config: {
3113
+ ...mockSessionRetrieveResponse.config,
3114
+ preload: { tools: 'all' },
3115
+ },
3116
+ experimental: {
3117
+ custom_tools: [
3118
+ {
3119
+ slug: 'LOCAL_GREP',
3120
+ original_slug: 'GREP',
3121
+ extends_toolkit: null,
3122
+ },
3123
+ ],
3124
+ },
3125
+ });
3126
+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3127
+ mockClient.toolRouter.session.search.mockResolvedValueOnce({
3128
+ success: true,
3129
+ error: null,
3130
+ results: [],
3131
+ tool_schemas: {},
3132
+ toolkit_connection_statuses: [],
3133
+ next_steps_guidance: [],
3134
+ session: {
3135
+ id: sessionId,
3136
+ generate_id: false,
3137
+ instructions: 'Reuse session',
3138
+ },
3139
+ time_info: {
3140
+ current_time_utc: '2025-03-09T12:00:00.000Z',
3141
+ current_time_utc_epoch_seconds: 1741521600,
3142
+ message: 'UTC',
3143
+ },
3144
+ });
3145
+
3146
+ const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
3147
+ await session.tools();
3148
+ await session.search({ query: 'search local text' });
3149
+
3150
+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
3151
+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
3152
+ expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(sessionId, {
3153
+ queries: [{ use_case: 'search local text' }],
3154
+ experimental: {
3155
+ custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],
3156
+ },
3157
+ });
3158
+ });
3159
it('should handle different session IDs', async () => {
3160
const session1Response = {
3161
...mockSessionRetrieveResponse,
@@ -3068,7 +3167,7 @@ describe('ToolRouter', () => {
3167
session_id: 'session_2',
3168
};
3169
3071
- mockClient.post
3170
+ mockClient.toolRouter.session.retrieve
3171
.mockResolvedValueOnce(session1Response)
3172
.mockResolvedValueOnce(session2Response);
3173
@@ -3077,13 +3176,14 @@ describe('ToolRouter', () => {
3176
3177
expect(session1.sessionId).toBe('session_1');
3178
expect(session2.sessionId).toBe('session_2');
3080
- expect(mockClient.post).toHaveBeenCalledTimes(2);
3081
- expect(mockClient.post).toHaveBeenNthCalledWith(1, attachEndpoint('session_1'), { body: {} });
3082
- expect(mockClient.post).toHaveBeenNthCalledWith(2, attachEndpoint('session_2'), { body: {} });
3179
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(2);
3180
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(1, 'session_1');
3181
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(2, 'session_2');
3182
+ expect(mockClient.post).not.toHaveBeenCalled();
3183
});
3184
3185
it('should handle MCP server type correctly', async () => {
3086
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
3186
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3187
3188
const session = await toolRouter.use(sessionId);
3189
@@ -3091,21 +3191,22 @@ describe('ToolRouter', () => {
3191
expect(session.mcp.url).toBe('https://mcp.example.com/session_123');
3192
});
3193
3094
- it('should throw error if session attach fails', async () => {
3194
+ it('should throw error if session retrieve fails', async () => {
3195
const error = new Error('Session not found');
3096
- mockClient.post.mockRejectedValueOnce(error);
3196
+ mockClient.toolRouter.session.retrieve.mockRejectedValueOnce(error);
3197
3198
await expect(toolRouter.use(sessionId)).rejects.toThrow('Session not found');
3099
- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), { body: {} });
3199
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId);
3200
+ expect(mockClient.post).not.toHaveBeenCalled();
3201
});
3202
3102
- it('should handle attach with different tool lists', async () => {
3203
+ it('should handle retrieve with different tool lists', async () => {
3204
const customResponse = {
3205
...mockSessionRetrieveResponse,
3206
tool_router_tools: ['CUSTOM_TOOL_1', 'CUSTOM_TOOL_2'],
3207
};
3208
3108
- mockClient.post.mockResolvedValueOnce(customResponse);
3209
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);
3210
3211
const session = await toolRouter.use(sessionId);
3212
@@ -3115,7 +3216,7 @@ describe('ToolRouter', () => {
3216
3217
it('should be independent from create method', async () => {
3218
mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3118
- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);
3219
+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3220
3221
// Create a new session
3222
const createdSession = await toolRouter.create('user_123');
@@ -3127,8 +3228,8 @@ describe('ToolRouter', () => {
3228
3229
// Both should have been called once
3230
expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
3130
- expect(mockClient.post).toHaveBeenCalledTimes(1);
3131
- expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
3231
+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(1);
3232
+ expect(mockClient.post).not.toHaveBeenCalled();
3233
});
3234
});
3235
});