Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
Refine ToolRouter preload docs and constants
Dhawal Upadhyaybccd32beaef0
diff --git a/.changeset/toolrouter-direct-tools-preset.md b/.changeset/toolrouter-direct-tools-preset.mdnew file mode 100644index 000000000..2f2b5c783--- /dev/null+++ b/.changeset/toolrouter-direct-tools-preset.md@@ -0,0 +1,5 @@+---+'@composio/core': patch+---++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.diff --git a/.changeset/toolrouter-preload-direct-customs.md b/.changeset/toolrouter-preload-direct-customs.mdnew file mode 100644index 000000000..72c9ffc77--- /dev/null+++ b/.changeset/toolrouter-preload-direct-customs.md@@ -0,0 +1,5 @@+---+'@composio/core': patch+---++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.diff --git a/python/composio/__init__.py b/python/composio/__init__.pyindex 3f1b91bd3..32b369257 100644--- a/python/composio/__init__.py+++ b/python/composio/__init__.py@@ -4,6 +4,7 @@ from .core.models.custom_tool_types import (CustomTool,SessionContext,)+from .core.models.tool_router_constants import SESSION_PRESET_DIRECT_TOOLSfrom .core.models.tool_router_session_files import RemoteFilefrom .core.models.tools import (after_execute,@@ -35,6 +36,7 @@ __all__ = ("ExperimentalToolkit","RemoteFile","SessionContext",+ "SESSION_PRESET_DIRECT_TOOLS","ConnectionExpiredEvent","ConnectionState","ConnectionStatusEnum",diff --git a/python/composio/core/models/__init__.py b/python/composio/core/models/__init__.pyindex 8f732d9a0..f69dedec3 100644--- a/python/composio/core/models/__init__.py+++ b/python/composio/core/models/__init__.py@@ -9,6 +9,7 @@ from .custom_tool_types import ()from .mcp import MCPfrom .tool_router import ToolRouter+from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLSfrom .tool_router_session import ToolRouterSessionfrom .tool_router_session_files import RemoteFile, ToolRouterSessionFilesMountfrom .toolkits import Toolkits@@ -39,6 +40,7 @@ __all__ = ["RegisteredCustomToolkit","RemoteFile","SessionContext",+ "SESSION_PRESET_DIRECT_TOOLS","SingleConnectedAccountDetailedResponse","ToolRouter","ToolRouterSession",diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 825a5881d..86ede61ae 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -59,8 +59,12 @@ from .custom_tool_types import (CustomToolsMapEntry,CustomToolWireDefinition,)+from .tool_router_constants import PRELOAD_TOOLS_ALLif t.TYPE_CHECKING:+ from composio_client.types.tool_router.session_attach_response import (+ Experimental as SessionAttachResponseExperimental,+ )from composio_client.types.tool_router.session_create_response import (Experimental as SessionCreateResponseExperimental,)@@ -728,6 +732,7 @@ def build_custom_tools_map_from_response(toolkits: t.Optional[t.List[ExperimentalToolkit]],experimental: t.Optional[t.Union[+ "SessionAttachResponseExperimental","SessionCreateResponseExperimental","SessionRetrieveResponseExperimental",]@@ -804,7 +809,7 @@ def assert_no_custom_tool_slugs_in_preload(custom_tools_map: t.Optional[CustomToolsMap],) -> None:"""Reject legacy top-level preload of custom tool slugs."""- if preload_tools is None or preload_tools == "all":+ if preload_tools is None or preload_tools == PRELOAD_TOOLS_ALL:returnif isinstance(preload_tools, str):raise ValidationError(@@ -817,6 +822,8 @@ def assert_no_custom_tool_slugs_in_preload(for slug in preload_tools:normalized = slug.upper()if normalized.startswith(LOCAL_TOOL_PREFIX) or (+ # Top-level preload.tools is only for Composio-managed tool slugs.+ # Custom tools use preload=True on their SDK definitions instead.custom_tools_map is not Noneand (normalized in custom_tools_map.by_original_slugdiff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.pyindex 4ba81aa48..95afe393f 100644--- a/python/composio/core/models/custom_tool_types.py+++ b/python/composio/core/models/custom_tool_types.py@@ -10,6 +10,7 @@ import typing as tfrom dataclasses import dataclass, fieldimport typing_extensions as te+from composio_client.types.tool_router import session_create_paramsfrom pydantic import BaseModelfrom composio_client.types.tool_router.session_execute_response import (@@ -109,21 +110,27 @@ class CustomTool:preload: t.Optional[bool] = None-class CustomToolWireDefinition(te.TypedDict, total=False):- slug: te.Required[str]- name: te.Required[str]- description: te.Required[str]- input_schema: te.Required[t.Dict[str, t.Any]]- extends_toolkit: str- output_schema: t.Dict[str, t.Any]+class CustomToolWireDefinition(+ session_create_params.ExperimentalCustomTool,+ total=False,+):+ preload: bool+++class CustomToolkitToolWireDefinition(+ session_create_params.ExperimentalCustomToolkitTool,+ total=False,+):preload: boolclass CustomToolkitWireDefinition(te.TypedDict, total=False):- slug: te.Required[str]- name: te.Required[str]+ # Stainless 1.37.0 lacks the input-only SDK preload hint on custom+ # toolkits, so this mirrors the generated shape and adds that single field.description: te.Required[str]- tools: te.Required[t.List[CustomToolWireDefinition]]+ name: te.Required[str]+ slug: te.Required[str]+ tools: te.Required[t.Iterable[CustomToolkitToolWireDefinition]]preload: booldiff --git a/python/composio/core/models/inline_custom_tools_payload.py b/python/composio/core/models/inline_custom_tools_payload.pyindex 23234caad..20a6b096e 100644--- a/python/composio/core/models/inline_custom_tools_payload.py+++ b/python/composio/core/models/inline_custom_tools_payload.py@@ -4,6 +4,7 @@ import typing as tfrom composio_client import Omit, omitfrom composio_client.types.tool_router import (+ session_attach_params,session_execute_params,session_search_params,)@@ -11,13 +12,23 @@ from composio_client.types.tool_router import (from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload+def inline_custom_tools_attach_experimental(+ payload: t.Optional[InlineCustomToolsWirePayload],+) -> t.Union[session_attach_params.Experimental, Omit]:+ if payload is None:+ return omit+ # Stainless generates endpoint-specific experimental types with the same custom+ # definition shape, so this helper centralizes the structural cast.+ return t.cast(session_attach_params.Experimental, payload)++def inline_custom_tools_execute_experimental(payload: t.Optional[InlineCustomToolsWirePayload],) -> t.Union[session_execute_params.Experimental, Omit]:if payload is None:return omit- # The SDK wire payload is a structural subset of Stainless' endpoint-specific- # experimental payloads, with input-only preload hints on custom definitions.+ # Stainless generates endpoint-specific experimental types with the same custom+ # definition shape, so this helper centralizes the structural cast.return t.cast(session_execute_params.Experimental, payload)@@ -26,6 +37,6 @@ def inline_custom_tools_search_experimental() -> t.Union[session_search_params.Experimental, Omit]:if payload is None:return omit- # The SDK wire payload is a structural subset of Stainless' endpoint-specific- # experimental payloads, with input-only preload hints on custom definitions.+ # Stainless generates endpoint-specific experimental types with the same custom+ # definition shape, so this helper centralizes the structural cast.return t.cast(session_search_params.Experimental, payload)diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex c2bad36ba..db32f27c2 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -14,6 +14,12 @@ from enum import Enumimport typing_extensions as tefrom composio_client import omitfrom composio_client.types.tool_router import session_create_params+from composio_client.types.tool_router.session_attach_response import (+ SessionAttachResponse,+)+from composio_client.types.tool_router.session_retrieve_response import (+ SessionRetrieveResponse,+)from composio.client import HttpClientfrom composio.core.models.base import Resource@@ -31,14 +37,18 @@ from composio.core.models.custom_tool_types import (CustomToolsMap,InlineCustomToolsWirePayload,)-from composio_client.types.tool_router.session_retrieve_response import (- SessionRetrieveResponse,-)from composio.core.models.tool_router_session import (ToolRouterSession,ToolRouterSessionPreloadConfig,)from composio.core.models.tool_router_session_files import ToolRouterSessionFilesMount+from composio.core.models.tool_router_constants import (+ PRELOAD_TOOLS_ALL,+ SESSION_PRESET_DIRECT_TOOLS,+)+from composio.core.models.inline_custom_tools_payload import (+ inline_custom_tools_attach_experimental,+)from composio.core.provider import TTool, TToolCollectionfrom composio.core.provider.base import BaseProvider@@ -237,13 +247,26 @@ def _session_preload_config(preload: _SessionPreloadLike,) -> ToolRouterSessionPreloadConfig:tools = preload.tools- if tools == "all":- return ToolRouterSessionPreloadConfig(tools="all")+ if tools == PRELOAD_TOOLS_ALL:+ return ToolRouterSessionPreloadConfig(tools=PRELOAD_TOOLS_ALL)if isinstance(tools, list):return ToolRouterSessionPreloadConfig(tools=t.cast(t.List[str], tools))return ToolRouterSessionPreloadConfig(tools=[])+def _preloads_all_custom_tools(+ preload: t.Union[ToolRouterPreloadConfig, _SessionPreloadLike, None],+) -> bool:+ tools: t.Union[t.List[str], str, None]+ if preload is None:+ tools = None+ elif isinstance(preload, dict):+ tools = preload.get("tools")+ else:+ tools = preload.tools+ return tools == PRELOAD_TOOLS_ALL++def _apply_session_preset_defaults(session_preset: t.Optional[SessionPreset],manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],@@ -254,16 +277,52 @@ def _apply_session_preset_defaults(t.Optional[ToolRouterWorkbenchConfig],t.Optional[ToolRouterPreloadConfig],]:- if session_preset != "direct_tools":+ if session_preset != SESSION_PRESET_DIRECT_TOOLS:return manage_connections, workbench, preloadreturn (False if manage_connections is None else manage_connections,{"enable": False} if workbench is None else workbench,- {"tools": "all"} if preload is None else preload,+ {"tools": PRELOAD_TOOLS_ALL} if preload is None else preload,)+def _prepare_inline_custom_tools(+ *,+ custom_tools: t.Optional[t.List[CustomTool]],+ custom_toolkits: t.Optional[t.List[ExperimentalToolkit]],+ default_preload: bool = False,+ preload_tools: t.Optional[t.Union[t.Sequence[str], t.Literal["all"]]] = None,+) -> t.Optional[InlineCustomToolsWirePayload]:+ has_customs = bool(custom_tools or custom_toolkits)+ local_custom_tools_map = (+ build_custom_tools_map(custom_tools or [], custom_toolkits)+ if has_customs+ else None+ )++ # Top-level preload["tools"] is for Composio-managed slugs only. Custom tools+ # use their own preload flag, so reject LOCAL/custom slugs there before+ # serializing the inline custom definitions.+ assert_no_custom_tool_slugs_in_preload(preload_tools, local_custom_tools_map)++ inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None+ if has_customs:+ inline_custom_tools_payload = InlineCustomToolsWirePayload()+ if custom_tools:+ inline_custom_tools_payload["custom_tools"] = serialize_custom_tools(+ custom_tools,+ default_preload=default_preload,+ )+ if custom_toolkits:+ inline_custom_tools_payload["custom_toolkits"] = serialize_custom_toolkits(+ custom_toolkits,+ default_preload=default_preload,+ )++ return inline_custom_tools_payload++class ToolRouterAssistivePromptConfig(te.TypedDict, total=False):"""Configuration for assistive prompt generation.@@ -631,14 +690,12 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):tool allowed by positive session filters such as toolkits,tools, or tags; the backend validates and caps the final set.Example: {'tools': ['GMAIL_FETCH_EMAILS']}- :param session_preset: Optional session preset. 'direct_tools' exposes all tools- allowed by the session filters directly in session.tools()- and the MCP tool list, and disables meta tools by default- (search, multi-execute, manage-connections, and workbench).- Use when all needed tools are known upfront and helper/meta- tools are not needed. Without this preset, ToolRouter uses- the default configuration with meta tools enabled. Loading- many tools can increase model context usage.+ :param session_preset: Optional session preset. Use+ SESSION_PRESET_DIRECT_TOOLS when all needed tools are+ known upfront and should be exposed directly from+ session.tools() and the MCP tool list. It disables+ meta/helper tools by default; explicit overrides still win.+ Loading many tools can increase model context usage.:param experimental: Optional experimental configuration (ToolRouterExperimentalConfig).Note: These features are experimental and may change.Dict with:@@ -663,6 +720,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):toolkits=['github', 'slack'])+ # Create a direct-tools session when all needed tools are known upfront+ session = tool_router.create(+ user_id='user_123',+ session_preset=SESSION_PRESET_DIRECT_TOOLS,+ toolkits=['github']+ )+# Create a session with per-toolkit tool configurationsession = tool_router.create(user_id='user_123',@@ -731,18 +795,14 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):```"""- direct_tools_preset = session_preset == "direct_tools"+ direct_tools_preset = session_preset == SESSION_PRESET_DIRECT_TOOLSmanage_connections, workbench, preload = _apply_session_preset_defaults(session_preset=session_preset,manage_connections=manage_connections,workbench=workbench,preload=preload,)- default_custom_preload = preload is not None and preload.get("tools") == "all"- assert_no_custom_tool_slugs_in_preload(- preload.get("tools") if preload is not None else None,- None,- )+ default_custom_preload = _preloads_all_custom_tools(preload)# Parse manage_connections configmanage_connections = (@@ -884,12 +944,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):# experimental.assistive_prompt_config.user_timezonecustom_tools: t.Optional[t.List[CustomTool]] = Nonecustom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None- local_custom_tools_map: t.Optional[CustomToolsMap] = Noneinline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None+ experimental_payload: t.Dict[str, t.Any] = {}if experimental is not None:- experimental_payload: t.Dict[str, t.Any] = {}-assistive_prompt_config = experimental.get("assistive_prompt")if assistive_prompt_config is not None:user_timezone = assistive_prompt_config.get("user_timezone")@@ -901,43 +959,25 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):# Serialize custom tools and toolkits for the backendcustom_tools = experimental.get("custom_tools")custom_toolkits = experimental.get("custom_toolkits")- if custom_tools or custom_toolkits:- local_custom_tools_map = build_custom_tools_map(- custom_tools or [],- custom_toolkits,- )- assert_no_custom_tool_slugs_in_preload(- preload.get("tools") if preload is not None else None,- local_custom_tools_map,- )- if custom_tools:- experimental_payload["custom_tools"] = serialize_custom_tools(- custom_tools,- default_preload=default_custom_preload,- )- if custom_toolkits:- experimental_payload["custom_toolkits"] = serialize_custom_toolkits(- custom_toolkits,- default_preload=default_custom_preload,- )+ inline_custom_tools_payload = _prepare_inline_custom_tools(+ custom_tools=custom_tools,+ custom_toolkits=custom_toolkits,+ default_preload=default_custom_preload,+ preload_tools=preload.get("tools") if preload is not None else None,+ )+ if inline_custom_tools_payload:+ if "custom_tools" in inline_custom_tools_payload:+ experimental_payload["custom_tools"] = inline_custom_tools_payload[+ "custom_tools"+ ]+ if "custom_toolkits" in inline_custom_tools_payload:+ experimental_payload["custom_toolkits"] = inline_custom_tools_payload[+ "custom_toolkits"+ ]- if (- "custom_tools" in experimental_payload- or "custom_toolkits" in experimental_payload- ):- inline_custom_tools_payload = {}- if "custom_tools" in experimental_payload:- inline_custom_tools_payload["custom_tools"] = experimental_payload[- "custom_tools"- ]- if "custom_toolkits" in experimental_payload:- inline_custom_tools_payload["custom_toolkits"] = (- experimental_payload["custom_toolkits"]- )-- if experimental_payload:- create_params["experimental"] = experimental_payload+ if experimental_payload:+ create_params["experimental"] = experimental_payloadif self._provider is None:raise ValueError(@@ -1035,31 +1075,37 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):)has_customs = bool(custom_tools or custom_toolkits)- inline_custom_tools_payload: t.Optional[InlineCustomToolsWirePayload] = None+ attach_inline_custom_tools_payload = _prepare_inline_custom_tools(+ custom_tools=custom_tools,+ custom_toolkits=custom_toolkits,+ )+ inline_custom_tools_payload = attach_inline_custom_tools_payload+ session: t.Union[SessionAttachResponse, SessionRetrieveResponse]if has_customs:- inline_custom_tools_payload = InlineCustomToolsWirePayload()- if custom_tools:- inline_custom_tools_payload["custom_tools"] = serialize_custom_tools(- custom_tools- )- if custom_toolkits:- inline_custom_tools_payload["custom_toolkits"] = (- serialize_custom_toolkits(custom_toolkits)- )-- from urllib.parse import quote-- body = (- {"experimental": inline_custom_tools_payload}- if inline_custom_tools_payload is not None- else {}- )- session = self._client.post(- f"/api/v3.1/tool_router/session/{quote(session_id, safe='')}/attach",- body=body,- cast_to=SessionRetrieveResponse,- )+ session = self._client.tool_router.session.attach(+ session_id,+ experimental=inline_custom_tools_attach_experimental(+ attach_inline_custom_tools_payload+ ),+ )+ else:+ session = self._client.tool_router.session.retrieve(session_id)++ # For use(..., custom_tools=...), we only learn the existing session's+ # top-level preload config after attach returns. If that existing config+ # is preload.tools = "all", custom tools should follow the same+ # SDK-local direct exposure rule.+ default_custom_preload = _preloads_all_custom_tools(session.config.preload)+ if has_customs and default_custom_preload:+ # Attach already happened above with the caller's explicit custom+ # preload hints. This rebuild only changes the payload stored on+ # ToolRouterSession and reused by future search/execute calls.+ inline_custom_tools_payload = _prepare_inline_custom_tools(+ custom_tools=custom_tools,+ custom_toolkits=custom_toolkits,+ default_preload=True,+ )custom_tools_map: t.Optional[CustomToolsMap] = Noneuser_id: t.Optional[str] = None@@ -1073,6 +1119,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):preloaded_custom_tool_slugs = get_preloaded_custom_tool_slugs(custom_tools_map,+ default_preload=default_custom_preload,)files_mount = ToolRouterSessionFilesMount(self._client, session.session_id)@@ -1119,6 +1166,7 @@ __all__ = ["ToolRouterWorkbenchConfig","SandboxSize","SessionPreset",+ "SESSION_PRESET_DIRECT_TOOLS","ToolRouterMultiAccountConfig","ToolRouterPreloadConfig","ToolRouterExperimentalConfig",diff --git a/python/composio/core/models/tool_router_constants.py b/python/composio/core/models/tool_router_constants.pynew file mode 100644index 000000000..e369fe552--- /dev/null+++ b/python/composio/core/models/tool_router_constants.py@@ -0,0 +1,4 @@+import typing as t++SESSION_PRESET_DIRECT_TOOLS: t.Literal["direct_tools"] = "direct_tools"+PRELOAD_TOOLS_ALL: t.Literal["all"] = "all"diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex 478eb8730..b0eba3cf7 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -63,7 +63,7 @@ if t.TYPE_CHECKING:COMPOSIO_MULTI_EXECUTE_TOOL = "COMPOSIO_MULTI_EXECUTE_TOOL"DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX = (- "[Direct tool - call directly, no search or connection check needed beforehand.]"+ "[Direct tool - call directly, no search needed beforehand.]")MAX_PARALLEL_WORKERS = 5diff --git a/python/examples/tool_router/direct_tools_preset.py b/python/examples/tool_router/direct_tools_preset.pyindex 14475a73e..b5f8b7656 100644--- a/python/examples/tool_router/direct_tools_preset.py+++ b/python/examples/tool_router/direct_tools_preset.py@@ -1,10 +1,9 @@"""Tool Router direct_tools session preset with OpenAI Agents.-session_preset="direct_tools" is a shortcut for sessions where the full allowed-tool set is known upfront. It disables Tool Router meta/helper tools by default-and loads all tools allowed by the filters directly into session.tools() and the-MCP tool list.+SESSION_PRESET_DIRECT_TOOLS is a shortcut for sessions where the full allowed+tool set is known upfront. It loads all tools allowed by the filters directly+into session.tools() and the MCP tool list.Usage:COMPOSIO_API_KEY=... OPENAI_API_KEY=... python examples/tool_router/direct_tools_preset.py@@ -14,8 +13,9 @@ import osfrom agents import Agent, Runnerfrom composio_openai_agents import OpenAIAgentsProvider+from pydantic import BaseModel, Field-from composio import Composio+from composio import Composio, SESSION_PRESET_DIRECT_TOOLSdef require_env(name: str) -> str:@@ -32,30 +32,64 @@ composio = Composio()require_env("OPENAI_API_KEY")++class UserNoteInput(BaseModel):+ username: str = Field(description="Hacker News username, for example pg")+++hn_research = composio.experimental.Toolkit(+ slug="HN_RESEARCH",+ name="Hacker News research",+ description="Internal research notes for Hacker News users.",+)+++@hn_research.tool(+ slug="GET_USER_NOTE",+ name="Get Hacker News user note",+ description="Return an internal research note for a Hacker News username.",+)+def get_user_note(input: UserNoteInput, ctx):+ username = input.username.lower()+ return {+ "username": input.username,+ "note": (+ "Paul Graham; YC co-founder and essayist."+ if username == "pg"+ else f"No curated internal note for {input.username}."+ ),+ }++session = composio.create(user_id="direct-tools-example-user",- session_preset="direct_tools",+ session_preset=SESSION_PRESET_DIRECT_TOOLS,toolkits=["hackernews"],tools={"hackernews": {"enable": ["HACKERNEWS_GET_USER"]}},+ experimental={+ "custom_toolkits": [hn_research],+ },)tools = session.tools()+tool_names = [tool.name for tool in tools]+assert "HACKERNEWS_GET_USER" in tool_names+assert "LOCAL_HN_RESEARCH_GET_USER_NOTE" in tool_names+assert "COMPOSIO_SEARCH_TOOLS" not in tool_names+print("Direct tools exposed to the agent:")for tool in tools:print(f"- {tool.name}")agent = Agent(name="Direct Tools Demo Agent",- instructions=(- "Use the provided direct tools. The session is configured without Tool "- "Router meta/helper tools."- ),+ instructions="Use the provided tools to perform the task.",model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),tools=tools,)result = Runner.run_sync(agent,- 'Use the Hacker News tool to look up user "pg" and report their karma.',+ 'Look up user "pg" on Hacker News and include any internal research note.',)print(result.final_output)diff --git a/python/examples/tool_router/preload.py b/python/examples/tool_router/preload.pyindex 577015870..c9325c561 100644--- a/python/examples/tool_router/preload.py+++ b/python/examples/tool_router/preload.py@@ -144,16 +144,20 @@ session = composio.create()tools = session.tools()+tool_names = [tool.name for tool in tools]+assert "HACKERNEWS_GET_USER" in tool_names+assert "LOCAL_LOOKUP_INTERNAL_USER" in tool_names+assert "LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH" in tool_names+assert "LOCAL_SEARCH_INTERNAL_USERS" not in tool_names+assert "LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG" not in tool_names+print("Direct tools exposed to the agent:")for tool in tools:print(f"- {tool.name}")agent = Agent(name="Preload Demo Agent",- instructions=(- "Use the provided direct tools. Do not search for tools first; the "- "needed tools are already loaded."- ),+ instructions="Use the provided tools to perform the task.",model=os.environ.get("OPENAI_MODEL", "gpt-5.5"),tools=tools,)diff --git a/python/tests/test_tool_router.py b/python/tests/test_tool_router.pyindex 80c4ce758..b76d9cf16 100644--- a/python/tests/test_tool_router.py+++ b/python/tests/test_tool_router.py@@ -5,13 +5,11 @@ from unittest.mock import MagicMock, patchimport pytestfrom composio_client import omitfrom pydantic import BaseModel, Field-from composio_client.types.tool_router.session_retrieve_response import (- SessionRetrieveResponse,-)from composio.exceptions import ValidationErrorfrom composio.core.models.custom_tool import ExperimentalAPIfrom composio.core.models.tool_router import (+ SESSION_PRESET_DIRECT_TOOLS,ToolkitConnectionsDetails,ToolkitConnectionState,ToolRouter,@@ -59,7 +57,7 @@ def mock_client():client.tool_router.session.create.return_value = mock_session_responseclient.tool_router.session.retrieve.return_value = mock_session_response- client.post.return_value = mock_session_response+ client.tool_router.session.attach.return_value = mock_session_response# Mock link responsemock_link_response = MagicMock()@@ -680,7 +678,7 @@ class TestToolRouter:session = tool_router.create(user_id="user_123",- session_preset="direct_tools",+ session_preset=SESSION_PRESET_DIRECT_TOOLS,toolkits=["github"],)@@ -703,7 +701,7 @@ class TestToolRouter:session = tool_router.create(user_id="user_123",- session_preset="direct_tools",+ session_preset=SESSION_PRESET_DIRECT_TOOLS,toolkits=["github"],manage_connections=True,workbench={"enable": True},@@ -744,7 +742,7 @@ class TestToolRouter:tool_router.create(user_id="user_123",- session_preset="direct_tools",+ session_preset=SESSION_PRESET_DIRECT_TOOLS,toolkits=["github"],preload={"tools": ["GITHUB_CREATE_ISSUE"]},experimental={"custom_tools": [grep]},@@ -938,8 +936,10 @@ class TestToolRouter:tool_router.use(session_id="session_123")def test_use_session(self, tool_router, mock_client):- """Test attaching an existing session."""- mock_client.post.return_value.config.preload.tools = ["GMAIL_FETCH_EMAILS"]+ """Test retrieving an existing session."""+ mock_client.tool_router.session.retrieve.return_value.config.preload.tools = [+ "GMAIL_FETCH_EMAILS"+ ]session = tool_router.use(session_id="session_123")@@ -960,12 +960,9 @@ class TestToolRouter:assert callable(session.toolkits)assert session.preload.tools == ["GMAIL_FETCH_EMAILS"]- mock_client.post.assert_called_once_with(- "/api/v3.1/tool_router/session/session_123/attach",- body={},- cast_to=SessionRetrieveResponse,- )- mock_client.tool_router.session.retrieve.assert_not_called()+ mock_client.tool_router.session.retrieve.assert_called_once_with("session_123")+ mock_client.tool_router.session.attach.assert_not_called()+ mock_client.post.assert_not_called()def test_use_session_with_custom_tools(self, tool_router, mock_client):"""Test attaching custom tools when reusing a session."""@@ -978,7 +975,7 @@ class TestToolRouter:def grep(input: GrepInput, ctx):return {"matches": []}- mock_response = mock_client.post.return_value+ mock_response = mock_client.tool_router.session.attach.return_valuemock_response.experimental = MagicMock()mock_response.experimental.assistive_prompt = Nonemock_response.experimental.custom_toolkits = []@@ -990,18 +987,126 @@ class TestToolRouter:session = tool_router.use(session_id="session_123", custom_tools=[grep])- mock_client.post.assert_called_once()- assert mock_client.post.call_args.args[0] == (- "/api/v3.1/tool_router/session/session_123/attach"- )- kwargs = mock_client.post.call_args.kwargs- assert kwargs["cast_to"] is SessionRetrieveResponse- assert kwargs["body"]["experimental"]["custom_tools"][0]["slug"] == "GREP"- assert "custom_toolkits" not in kwargs["body"]["experimental"]+ mock_client.tool_router.session.attach.assert_called_once()+ kwargs = mock_client.tool_router.session.attach.call_args.kwargs+ assert kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"+ assert "custom_toolkits" not in kwargs["experimental"]mock_client.tool_router.session.retrieve.assert_not_called()+ mock_client.post.assert_not_called()assert session.custom_tools()[0].slug == "SERVER_GREP"assert session.custom_tools()[0].name == "Grep"+ @patch("composio.core.models.tools.Tools")+ def test_use_session_attaches_preloaded_custom_tools(+ self,+ mock_tools_class,+ tool_router,+ mock_client,+ mock_provider,+ ):+ """use() attaches customs and exposes SDK-preloaded schemas locally."""++ @experimental_api.tool(+ slug="GREP",+ name="Grep",+ description="Search local text",+ preload=True,+ )+ def grep(input: GrepInput, ctx):+ return {"matches": [input.pattern]}++ attach_response = mock_client.tool_router.session.attach.return_value+ attach_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]+ attach_response.config.preload.tools = []+ attach_response.experimental = MagicMock()+ attach_response.experimental.assistive_prompt = None+ attach_response.experimental.custom_toolkits = []+ mock_custom_tool = MagicMock()+ mock_custom_tool.slug = "LOCAL_GREP"+ mock_custom_tool.original_slug = "GREP"+ mock_custom_tool.extends_toolkit = None+ attach_response.experimental.custom_tools = [mock_custom_tool]++ mock_tools_instance = MagicMock()+ mock_tool = MagicMock()+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"+ mock_tool.toolkit.slug = "composio"+ mock_tool.input_parameters = {}+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}+ mock_tools_class.return_value = mock_tools_instance+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"++ session = tool_router.use(session_id="session_123", custom_tools=[grep])+ session.tools()++ mock_client.tool_router.session.attach.assert_called_once()+ attach_kwargs = mock_client.tool_router.session.attach.call_args.kwargs+ assert attach_kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"+ assert attach_kwargs["experimental"]["custom_tools"][0]["preload"] is True+ mock_client.post.assert_not_called()+ mock_client.tool_router.session.retrieve.assert_not_called()++ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]+ assert [tool.slug for tool in wrapped_tools] == [+ "COMPOSIO_SEARCH_TOOLS",+ "LOCAL_GREP",+ ]++ @patch("composio.core.models.tools.Tools")+ def test_use_session_applies_preload_all_to_custom_tools(+ self,+ mock_tools_class,+ tool_router,+ mock_client,+ mock_provider,+ ):+ """preload.tools='all' on an existing session selects attached customs."""++ @experimental_api.tool(+ slug="GREP",+ name="Grep",+ description="Search local text",+ )+ def grep(input: GrepInput, ctx):+ return {"matches": [input.pattern]}++ attach_response = mock_client.tool_router.session.attach.return_value+ attach_response.tool_router_tools = ["COMPOSIO_SEARCH_TOOLS"]+ attach_response.config.preload.tools = "all"+ attach_response.experimental = MagicMock()+ attach_response.experimental.assistive_prompt = None+ attach_response.experimental.custom_toolkits = []+ mock_custom_tool = MagicMock()+ mock_custom_tool.slug = "LOCAL_GREP"+ mock_custom_tool.original_slug = "GREP"+ mock_custom_tool.extends_toolkit = None+ attach_response.experimental.custom_tools = [mock_custom_tool]++ mock_tools_instance = MagicMock()+ mock_tool = MagicMock()+ mock_tool.slug = "COMPOSIO_SEARCH_TOOLS"+ mock_tool.toolkit.slug = "composio"+ mock_tool.input_parameters = {}+ mock_tools_instance.get_raw_tool_router_meta_tools.return_value = [mock_tool]+ mock_tools_instance._file_helper.enhance_schema_descriptions.return_value = {}+ mock_tools_class.return_value = mock_tools_instance+ mock_provider.wrap_tools.return_value = "mocked-custom-tools"++ session = tool_router.use(session_id="session_123", custom_tools=[grep])+ session.tools()+ session.search(query="search local text")++ wrapped_tools = mock_provider.wrap_tools.call_args.kwargs["tools"]+ assert [tool.slug for tool in wrapped_tools] == [+ "COMPOSIO_SEARCH_TOOLS",+ "LOCAL_GREP",+ ]+ mock_client.tool_router.session.search.assert_called_once()+ search_kwargs = mock_client.tool_router.session.search.call_args.kwargs+ assert search_kwargs["experimental"]["custom_tools"][0]["slug"] == "GREP"+ assert search_kwargs["experimental"]["custom_tools"][0]["preload"] is True+def test_use_session_with_different_user(self, tool_router, mock_client):"""Test that use() extracts user_id from session config."""mock_attach_response = MagicMock()@@ -1016,7 +1121,7 @@ class TestToolRouter:mock_attach_response.config.preload.tools = []mock_attach_response.experimental = None- mock_client.post.return_value = mock_attach_response+ mock_client.tool_router.session.retrieve.return_value = mock_attach_responsesession = tool_router.use(session_id="session_456")@@ -1024,8 +1129,10 @@ class TestToolRouter:assert session.mcp.type == ToolRouterMCPServerType.HTTPdef test_use_session_throws_error_on_failure(self, tool_router, mock_client):- """Test that use() throws error if attach fails."""- mock_client.post.side_effect = Exception("Session not found")+ """Test that use() throws error if retrieve fails."""+ mock_client.tool_router.session.retrieve.side_effect = Exception(+ "Session not found"+ )with pytest.raises(Exception, match="Session not found"):tool_router.use(session_id="invalid_session")@@ -1440,7 +1547,7 @@ class TestToolRouter:mock_attach_response.experimental = Nonemock_client.tool_router.session.create.return_value = mock_create_response- mock_client.post.return_value = mock_attach_response+ mock_client.tool_router.session.retrieve.return_value = mock_attach_response# Create a new sessioncreated_session = tool_router.create(user_id="user_123")@@ -1452,12 +1559,10 @@ class TestToolRouter:# Verify both methods were calledmock_client.tool_router.session.create.assert_called_once()- mock_client.post.assert_called_once_with(- "/api/v3.1/tool_router/session/retrieved_session/attach",- body={},- cast_to=SessionRetrieveResponse,+ mock_client.tool_router.session.retrieve.assert_called_once_with(+ "retrieved_session")- mock_client.tool_router.session.retrieve.assert_not_called()+ mock_client.post.assert_not_called()class TestToolRouterTypes:@@ -1811,8 +1916,8 @@ class TestToolRouterIntegration:created_session = tool_router.create(user_id="user_123")created_session_id = created_session.session_id- # Setup attach to return the same session- mock_client.post.return_value = (+ # Setup retrieve to return the same session+ mock_client.tool_router.session.retrieve.return_value = (mock_client.tool_router.session.create.return_value)diff --git a/ts/examples/tool-router/README.md b/ts/examples/tool-router/README.mdindex f40b6ddd8..80c9cde07 100644--- a/ts/examples/tool-router/README.md+++ b/ts/examples/tool-router/README.md@@ -5,11 +5,13 @@ This example demonstrates how to use Composio SDK for tool-router.## Setup1. **Install dependencies:**+```bashpnpm install```2. **Configure environment:**+```bashcp .env.example .env```@@ -41,11 +43,12 @@ pnpm direct-tools- Fetches available tools- Demonstrates basic usage patterns- Shows how to preload selected app tools and SDK-local custom tools into `session.tools()`-- Shows `sessionPreset: "direct_tools"` for loading all tools allowed by session filters without meta/helper tools+- Shows `SessionPreset.DIRECT_TOOLS` for loading all tools allowed by session filters without meta/helper tools## CustomizationEdit `src/index.ts` to:+- Add specific apps you want to integrate with- Implement your business logic- Add error handling and loggingdiff --git a/ts/examples/tool-router/src/direct-tools-preset.ts b/ts/examples/tool-router/src/direct-tools-preset.tsindex 10474c808..dfa820a17 100644--- a/ts/examples/tool-router/src/direct-tools-preset.ts+++ b/ts/examples/tool-router/src/direct-tools-preset.ts@@ -1,7 +1,7 @@/*** Tool Router direct_tools session preset with OpenAI Agents*- * `sessionPreset: "direct_tools"` is a shortcut for sessions where the full+ * `sessionPreset: SessionPreset.DIRECT_TOOLS` is a shortcut for sessions where the full* allowed tool set is known upfront. It disables Tool Router meta/helper tools* by default and loads all tools allowed by the filters directly into* `session.tools()` and the MCP tool list.@@ -10,9 +10,16 @@* COMPOSIO_API_KEY=... OPENAI_API_KEY=... bun src/direct-tools-preset.ts*/import 'dotenv/config';-import { Composio } from '@composio/core';+import assert from 'node:assert/strict';+import {+ Composio,+ SessionPreset,+ experimental_createTool,+ experimental_createToolkit,+} from '@composio/core';import { OpenAIAgentsProvider } from '@composio/openai-agents';import { Agent, run } from '@openai/agents';+import { z } from 'zod/v3';function requireEnv(name: 'COMPOSIO_API_KEY' | 'OPENAI_API_KEY'): string {const value = process.env[name];@@ -31,17 +38,46 @@ const composio = new Composio({provider: new OpenAIAgentsProvider(),});+const getUserNote = experimental_createTool('GET_USER_NOTE', {+ name: 'Get Hacker News user note',+ description: 'Return an internal research note for a Hacker News username.',+ inputParams: z.object({+ username: z.string().describe('Hacker News username, for example pg'),+ }),+ execute: async ({ username }) => ({+ username,+ note:+ username.toLowerCase() === 'pg'+ ? 'Paul Graham; YC co-founder and essayist.'+ : `No curated internal note for ${username}.`,+ }),+});++const hnResearch = experimental_createToolkit('HN_RESEARCH', {+ name: 'Hacker News research',+ description: 'Internal research notes for Hacker News users.',+ tools: [getUserNote],+});+const session = await composio.create('direct-tools-example-user', {- sessionPreset: 'direct_tools',+ sessionPreset: SessionPreset.DIRECT_TOOLS,toolkits: ['hackernews'],tools: {hackernews: {enable: ['HACKERNEWS_GET_USER'],},},+ experimental: {+ customToolkits: [hnResearch],+ },});const tools = await session.tools();+const toolNames = tools.map(tool => tool.name);+assert(toolNames.includes('HACKERNEWS_GET_USER'));+assert(toolNames.includes('LOCAL_HN_RESEARCH_GET_USER_NOTE'));+assert(!toolNames.includes('COMPOSIO_SEARCH_TOOLS'));+console.log('Direct tools exposed to the agent:');for (const tool of tools) {console.log(`- ${tool.name}`);@@ -49,15 +85,14 @@ for (const tool of tools) {const agent = new Agent({name: 'Direct Tools Demo Agent',- instructions:- 'Use the provided direct tools. The session is configured without Tool Router meta/helper tools.',+ instructions: 'Use the provided tools to perform the task.',model: process.env.OPENAI_MODEL ?? 'gpt-5.5',tools,});const prompt =process.argv.slice(2).join(' ') ||- 'Use the Hacker News tool to look up user "pg" and report their karma.';+ 'Look up user "pg" on Hacker News and include any internal research note.';console.log(`\nUser: ${prompt}\n`);const result = await run(agent, prompt);diff --git a/ts/examples/tool-router/src/preload.ts b/ts/examples/tool-router/src/preload.tsindex 6110e47f1..5c33b757c 100644--- a/ts/examples/tool-router/src/preload.ts+++ b/ts/examples/tool-router/src/preload.ts@@ -9,6 +9,7 @@* COMPOSIO_API_KEY=... OPENAI_API_KEY=... bun src/preload.ts*/import 'dotenv/config';+import assert from 'node:assert/strict';import { Composio, experimental_createTool, experimental_createToolkit } from '@composio/core';import { OpenAIAgentsProvider } from '@composio/openai-agents';import { Agent, run } from '@openai/agents';@@ -129,6 +130,13 @@ const session = await composio.create('preload-example-user', {});const tools = await session.tools();+const toolNames = tools.map(tool => tool.name);+assert(toolNames.includes('HACKERNEWS_GET_USER'));+assert(toolNames.includes('LOCAL_LOOKUP_INTERNAL_USER'));+assert(toolNames.includes('LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_HEALTH'));+assert(!toolNames.includes('LOCAL_SEARCH_INTERNAL_USERS'));+assert(!toolNames.includes('LOCAL_INTERNAL_ADMIN_GET_ACCOUNT_AUDIT_LOG'));+console.log('Direct tools exposed to the agent:');for (const tool of tools) {console.log(`- ${tool.name}`);@@ -136,8 +144,7 @@ for (const tool of tools) {const agent = new Agent({name: 'Preload Demo Agent',- instructions:- 'Use the provided direct tools. Do not search for tools first; the needed tools are already loaded.',+ instructions: 'Use the provided tools to perform the task.',model: process.env.OPENAI_MODEL ?? 'gpt-5.5',tools,});diff --git a/ts/packages/core/src/composio.ts b/ts/packages/core/src/composio.tsindex daba9074e..cb03ac591 100644--- a/ts/packages/core/src/composio.ts+++ b/ts/packages/core/src/composio.ts@@ -203,6 +203,8 @@ export class Composio<toolRouter: ToolRouter<unknown, unknown, TProvider>;/*** Creates a new tool router session for a user.+ * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools+ * should be exposed directly; see `ToolRouterCreateSessionConfig`.** @param userId {string} The user id to create the session for* @param config {ToolRouterConfig} The config for the tool router sessiondiff --git a/ts/packages/core/src/lib/toolRouterConstants.ts b/ts/packages/core/src/lib/toolRouterConstants.tsnew file mode 100644index 000000000..4ce29481f--- /dev/null+++ b/ts/packages/core/src/lib/toolRouterConstants.ts@@ -0,0 +1 @@+export const PRELOAD_TOOLS_ALL = 'all' as const;diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex 65ab8d228..5741e0fdd 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -41,6 +41,7 @@ import type {SessionRetrieveResponse,} from '@composio/client/resources/tool-router/session/session.mjs';import { ValidationError } from '../errors';+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';/** Prefix applied by the backend to local tool slugs for disambiguation. */export const LOCAL_TOOL_PREFIX = 'LOCAL_';@@ -519,16 +520,18 @@ export function findCustomToolMapEntryByFinalSlug(* @internal*/export function assertNoCustomToolSlugsInPreload(- preloadTools: readonly string[] | 'all' | undefined,+ preloadTools: readonly string[] | typeof PRELOAD_TOOLS_ALL | undefined,customToolsMap: CustomToolsMap | undefined): void {- if (!preloadTools || preloadTools === 'all') {+ if (!preloadTools || preloadTools === PRELOAD_TOOLS_ALL) {return;}const customPreloadSlugs = preloadTools.filter(slug => {const normalized = slug.toUpperCase();return (+ // Top-level preload.tools is only for Composio-managed tool slugs.+ // Custom tools use `preload: true` on their SDK definitions instead.normalized.startsWith(LOCAL_TOOL_PREFIX) ||customToolsMap?.byOriginalSlug.has(normalized) ||customToolsMap?.byFinalSlug.has(normalized)diff --git a/ts/packages/core/src/models/ToolRouter.ts b/ts/packages/core/src/models/ToolRouter.tsindex 0d7e21c66..4014a03f8 100644--- a/ts/packages/core/src/models/ToolRouter.ts+++ b/ts/packages/core/src/models/ToolRouter.ts@@ -28,9 +28,11 @@ import {MCPServerType,ToolRouterMCPServerConfig,ToolRouterSessionMetadata,+ SessionPreset,} from '../types/toolRouter.types';import { ToolRouterCreateSessionConfigSchema } from '../types/toolRouter.types';import {+ SessionAttachResponse,SessionCreateParams,SessionCreateResponse,SessionRetrieveResponse,@@ -48,6 +50,7 @@ import {transformToolRouterToolkitsParams,transformToolRouterMultiAccountParams,} from '../lib/toolRouterParams';+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';import { ToolRouterSession } from './ToolRouterSession';import {assertNoCustomToolSlugsInPreload,@@ -59,7 +62,9 @@ import {} from './CustomTool';import type { CustomToolsMap } from '../types/customTool.types';-function getSessionMetadata(session: SessionCreateResponse | SessionRetrieveResponse) {+function getSessionMetadata(+ session: SessionCreateResponse | SessionRetrieveResponse | SessionAttachResponse+) {const metadata: ToolRouterSessionMetadata = {preload: session.config.preload,configVersion: session.config_version,@@ -68,6 +73,45 @@ function getSessionMetadata(session: SessionCreateResponse | SessionRetrieveRespreturn metadata;}+function preloadsAllCustomTools(preload?: { tools?: readonly string[] | string }): boolean {+ return preload?.tools === PRELOAD_TOOLS_ALL;+}++function prepareInlineCustomTools(options: {+ customTools?: CustomTool[];+ customToolkits?: CustomToolkit[];+ defaultPreload?: boolean;+ preloadTools?: readonly string[] | typeof PRELOAD_TOOLS_ALL;+}): InlineCustomToolsWirePayload | undefined {+ const { customTools, customToolkits, defaultPreload = false, preloadTools } = options;+ const hasCustoms = !!(customTools?.length || customToolkits?.length);+ const localCustomToolsMap = hasCustoms+ ? buildCustomToolsMap(customTools ?? [], customToolkits)+ : undefined;++ // Top-level preload.tools is for Composio-managed slugs only. Custom tools+ // use their own preload flag, so reject LOCAL/custom slugs there before+ // serializing the inline custom definitions.+ assertNoCustomToolSlugsInPreload(preloadTools, localCustomToolsMap);++ const serializedTools = customTools?.length+ ? serializeCustomTools(customTools, { defaultPreload })+ : undefined;+ const serializedToolkits = customToolkits?.length+ ? serializeCustomToolkits(customToolkits, { defaultPreload })+ : undefined;++ const inlineCustomToolsPayload =+ serializedTools || serializedToolkits+ ? {+ ...(serializedTools ? { custom_tools: serializedTools } : {}),+ ...(serializedToolkits ? { custom_toolkits: serializedToolkits } : {}),+ }+ : undefined;++ return inlineCustomToolsPayload;+}+export class ToolRouter<TToolCollection,TTool,@@ -98,6 +142,8 @@ export class ToolRouter</*** Creates a new tool router session for a user.+ * Use `sessionPreset: SessionPreset.DIRECT_TOOLS` when all needed tools+ * should be exposed directly; see `ToolRouterCreateSessionConfig`.** @param userId {string} The user id to create the session for* @param config {ToolRouterCreateSessionConfig} The config for the tool router session@@ -105,7 +151,7 @@ export class ToolRouter<** @example* ```typescript- * import { Composio, experimental_createTool } from '@composio/core';+ * import { Composio } from '@composio/core';** const composio = new Composio();*@@ -117,16 +163,6 @@ export class ToolRouter<* customToolkits: [myToolkit],* },* });- *- * // Custom tools are searched by default. Set `preload: true` on a custom- * // tool or toolkit to expose it directly from `session.tools()`.- *- * // Expose all tools allowed by filters directly, without meta/helper tools.- * // `preload.tools = "all"` requires a positive filter such as `toolkits`.- * const directSession = await composio.create('user_123', {- * sessionPreset: 'direct_tools',- * toolkits: ['github'],- * });* ```*/async create(@@ -134,17 +170,18 @@ export class ToolRouter<config?: ToolRouterCreateSessionConfig): Promise<Session<TToolCollection, TTool, TProvider>> {const routerConfig = ToolRouterCreateSessionConfigSchema.parse(config ?? {});- const isDirectToolsPreset = routerConfig.sessionPreset === 'direct_tools';+ const isDirectToolsPreset = routerConfig.sessionPreset === SessionPreset.DIRECT_TOOLS;// Extract custom tools/toolkits from experimental configconst customTools = routerConfig.experimental?.customTools;const customToolkits = routerConfig.experimental?.customToolkits;- const defaultCustomPreload = routerConfig.preload?.tools === 'all';- const localCustomToolsMap =- customTools?.length || customToolkits?.length- ? buildCustomToolsMap(customTools ?? [], customToolkits)- : undefined;- assertNoCustomToolSlugsInPreload(routerConfig.preload?.tools, localCustomToolsMap);+ const defaultCustomPreload = preloadsAllCustomTools(routerConfig.preload);+ const inlineCustomToolsPayload = prepareInlineCustomTools({+ customTools,+ customToolkits,+ defaultPreload: defaultCustomPreload,+ preloadTools: routerConfig.preload?.tools,+ });// Build the typed experimental payload for the backendconst experimentalPayload: SessionCreateParams['experimental'] = {};@@ -155,27 +192,12 @@ export class ToolRouter<};}- if (customTools?.length) {- experimentalPayload.custom_tools = serializeCustomTools(customTools, {- defaultPreload: defaultCustomPreload,- });+ if (inlineCustomToolsPayload?.custom_tools) {+ experimentalPayload.custom_tools = inlineCustomToolsPayload.custom_tools;}- if (customToolkits?.length) {- experimentalPayload.custom_toolkits = serializeCustomToolkits(customToolkits, {- defaultPreload: defaultCustomPreload,- });+ if (inlineCustomToolsPayload?.custom_toolkits) {+ experimentalPayload.custom_toolkits = inlineCustomToolsPayload.custom_toolkits;}- const inlineCustomToolsPayload =- experimentalPayload.custom_tools || experimentalPayload.custom_toolkits- ? {- ...(experimentalPayload.custom_tools- ? { custom_tools: experimentalPayload.custom_tools }- : {}),- ...(experimentalPayload.custom_toolkits- ? { custom_toolkits: experimentalPayload.custom_toolkits }- : {}),- }- : undefined;const multiAccountPayload = transformToolRouterMultiAccountParams(routerConfig.multiAccount);@@ -256,24 +278,36 @@ export class ToolRouter<const customToolkits = options?.customToolkits;const hasCustoms = !!(customTools?.length || customToolkits?.length);- let inlineCustomToolsPayload: InlineCustomToolsWirePayload | undefined;+ let session: SessionRetrieveResponse | SessionAttachResponse;+ const attachInlineCustomToolsPayload = prepareInlineCustomTools({+ customTools,+ customToolkits,+ });+ let inlineCustomToolsPayload = attachInlineCustomToolsPayload;if (hasCustoms) {- const serializedTools = customTools?.length ? serializeCustomTools(customTools) : undefined;- const serializedToolkits = customToolkits?.length- ? serializeCustomToolkits(customToolkits)- : undefined;-- inlineCustomToolsPayload = {- ...(serializedTools ? { custom_tools: serializedTools } : {}),- ...(serializedToolkits ? { custom_toolkits: serializedToolkits } : {}),- };+ session = await this.client.toolRouter.session.attach(id, {+ experimental: attachInlineCustomToolsPayload,+ });+ } else {+ session = await this.client.toolRouter.session.retrieve(id);}- const session = await this.client.post<SessionRetrieveResponse>(- `/api/v3.1/tool_router/session/${encodeURIComponent(id)}/attach`,- { body: inlineCustomToolsPayload ? { experimental: inlineCustomToolsPayload } : {} }- );+ // For use(...customTools), we only learn the existing session's top-level+ // preload config after attach returns. If that existing config is+ // preload.tools = "all", custom tools should follow the same SDK-local+ // direct exposure rule.+ const defaultCustomPreload = preloadsAllCustomTools(session.config.preload);+ if (hasCustoms && defaultCustomPreload) {+ // Attach already happened above with the caller's explicit custom preload+ // hints. This rebuild only changes the payload stored on ToolRouterSession+ // and reused by future search/execute calls.+ inlineCustomToolsPayload = prepareInlineCustomTools({+ customTools,+ customToolkits,+ defaultPreload: true,+ });+ }let customToolsMap: CustomToolsMap | undefined;let userId: string | undefined;@@ -288,7 +322,7 @@ export class ToolRouter<const metadata = {...getSessionMetadata(session),- preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap),+ preloadedCustomToolSlugs: getPreloadedCustomToolSlugs(customToolsMap, defaultCustomPreload),inlineCustomToolsPayload,};diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex 9957649ef..37d626a40 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -55,7 +55,7 @@ import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';const COMPOSIO_MULTI_EXECUTE_TOOL = 'COMPOSIO_MULTI_EXECUTE_TOOL';export const DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX =- '[Direct tool - call directly, no search or connection check needed beforehand.]';+ '[Direct tool - call directly, no search needed beforehand.]';export class ToolRouterSession<TToolCollection,@@ -147,7 +147,7 @@ export class ToolRouterSession<toolSlug,input,modifiers,- toolBySlug.get(toolSlug.toUpperCase()),+ toolBySlug.get(toolSlug.toUpperCase()));};diff --git a/ts/packages/core/src/models/inlineCustomToolsPayload.ts b/ts/packages/core/src/models/inlineCustomToolsPayload.tsindex 78ed4cc66..825c76a34 100644--- a/ts/packages/core/src/models/inlineCustomToolsPayload.ts+++ b/ts/packages/core/src/models/inlineCustomToolsPayload.ts@@ -11,7 +11,7 @@ type InlineCustomToolsExperimental =export function inlineCustomToolsExperimental<TExperimental extends InlineCustomToolsExperimental>(payload?: InlineCustomToolsWirePayload): TExperimental | undefined {- // The SDK wire payload is a structural subset of Stainless' endpoint-specific- // experimental payloads, with input-only preload hints on custom definitions.+ // Stainless generates endpoint-specific experimental types with the same custom+ // definition shape, so this helper centralizes the structural cast.return payload as TExperimental | undefined;}diff --git a/ts/packages/core/src/types/customTool.types.ts b/ts/packages/core/src/types/customTool.types.tsindex 2ae59d8a8..f9e23b7d7 100644--- a/ts/packages/core/src/types/customTool.types.ts+++ b/ts/packages/core/src/types/customTool.types.ts@@ -139,7 +139,7 @@ export const CreateCustomToolBaseSchema = z.object({.boolean().optional().describe(- 'When true, expose this custom tool directly from session.tools(). This is SDK-local for custom tools and is sent to v3.1 with the inline custom definition.'+ 'When true, include this custom tool in session.tools() so it can be called without searching first.'),});@@ -170,9 +170,8 @@ export interface CustomTool {*/readonly extendsToolkit?: string;/**- * Whether this custom tool should be exposed directly from session.tools().- * This is SDK-local for custom tools and is sent to v3.1 with the inline- * custom definition.+ * Include this custom tool in session.tools() so it can be called without+ * searching first.*/readonly preload?: boolean;readonly inputSchema: Record<string, unknown>;@@ -187,9 +186,7 @@ export interface CustomTool {/** Serialized tool definition sent to backend for search indexing. Uses official client type. */export type CustomToolDefinition = SessionCreateParams.Experimental.CustomTool;-export type CustomToolWireDefinition = CustomToolDefinition & {- preload?: boolean;-};+export type CustomToolWireDefinition = CustomToolDefinition;// ────────────────────────────────────────────────────────────────// Custom toolkit types@@ -206,7 +203,7 @@ export const CreateCustomToolkitBaseSchema = z.object({.boolean().optional().describe(- 'When true, expose tools in this custom toolkit directly from session.tools(). Tool-level preload values override this default.'+ 'When true, include tools from this custom toolkit in session.tools(). Tool-level preload values override this default.'),});@@ -225,7 +222,7 @@ export interface CustomToolkit {readonly name: string;readonly description: string;/**- * Default direct-exposure setting for tools in this custom toolkit.+ * Default session.tools() exposure for tools in this custom toolkit.* Tool-level preload values override this default.*/readonly preload?: boolean;@@ -235,10 +232,7 @@ export interface CustomToolkit {/** Serialized toolkit definition sent to backend. Uses official client type. */export type CustomToolkitDefinition = SessionCreateParams.Experimental.CustomToolkit;-export type CustomToolkitWireDefinition = Omit<CustomToolkitDefinition, 'tools'> & {- preload?: boolean;- tools: Array<CustomToolkitDefinition['tools'][number] & { preload?: boolean }>;-};+export type CustomToolkitWireDefinition = CustomToolkitDefinition;export interface InlineCustomToolsWirePayload {custom_tools?: CustomToolWireDefinition[];@@ -266,7 +260,7 @@ export type CustomToolsMap = {byOriginalSlug: Map<string, CustomToolsMapEntry>;/** The original custom toolkits passed at session creation — used for session.customToolkits() */toolkits?: CustomToolkit[];- /** The original standalone custom tools passed at session creation — kept for inline re-injection on subsequent v3.1 requests. */+ /** The original standalone custom tools passed at session creation — kept for inline re-injection on later requests. */tools?: CustomTool[];};diff --git a/ts/packages/core/src/types/toolRouter.types.ts b/ts/packages/core/src/types/toolRouter.types.tsindex 1c0464f86..2e553edb6 100644--- a/ts/packages/core/src/types/toolRouter.types.ts+++ b/ts/packages/core/src/types/toolRouter.types.ts@@ -11,6 +11,12 @@ import type {RegisteredCustomTool,RegisteredCustomToolkit,} from './customTool.types';+import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';++export const SessionPreset = {+ DIRECT_TOOLS: 'direct_tools',+} as const;+export type SessionPreset = (typeof SessionPreset)[keyof typeof SessionPreset];export const MCPServerTypeSchema = z.enum(['http', 'sse']);export type MCPServerType = z.infer<typeof MCPServerTypeSchema>;@@ -173,7 +179,7 @@ export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;const ToolRouterCreateSessionConfigBaseSchema = z.object({sessionPreset: z- .literal('direct_tools')+ .literal(SessionPreset.DIRECT_TOOLS).optional().describe('Shortcut to expose every tool allowed by the session filters directly in session.tools() and the MCP tool list. This disables meta tools by default (search, multi-execute, manage-connections, and workbench). Use when all tools are known upfront and helper/meta tools are not needed. Without this preset, ToolRouter uses its default configuration with meta tools enabled.'@@ -273,7 +279,7 @@ const ToolRouterCreateSessionConfigBaseSchema = zpreload: z.object({tools: z- .union([z.array(z.string()), z.literal('all')])+ .union([z.array(z.string()), z.literal(PRELOAD_TOOLS_ALL)]).optional().describe('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 => {}const config = value as Record<string, unknown>;- if (config.sessionPreset !== 'direct_tools') {+ if (config.sessionPreset !== SessionPreset.DIRECT_TOOLS) {return value;}@@ -329,7 +335,7 @@ const applyDirectToolsPresetDefaults = (value: unknown): unknown => {...config,manageConnections: config.manageConnections === undefined ? false : config.manageConnections,workbench: config.workbench === undefined ? { enable: false } : config.workbench,- preload: config.preload === undefined ? { tools: 'all' } : config.preload,+ preload: config.preload === undefined ? { tools: PRELOAD_TOOLS_ALL } : config.preload,};};@@ -339,7 +345,7 @@ export const ToolRouterCreateSessionConfigSchema = z/*** The config for the tool router session.*- * @param {'direct_tools'} [sessionPreset] - Shortcut that exposes every tool allowed by the session filters directly in session.tools() and the MCP tool list. Disables search, multi-execute, manage-connections, and workbench by default; explicit overrides for supported fields still win. Without this preset, ToolRouter uses the default configuration with meta tools enabled.+ * @param {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.* @param {ToolRouterToolkitsParamSchema | ToolRouterToolkitsDisabledConfigSchema | ToolRouterToolkitsEnabledConfigSchema} toolkits - The toolkits to use in the tool router session* @param {Record<string, ToolRouterToolsParam | ToolRouterConfigTools>} tools - The tools to configure per toolkit (key is toolkit slug)* @param {Array<'readOnlyHint' | 'destructiveHint' | 'idempotentHint' | 'openWorldHint'>} tags - Global tags to filter tools by behaviordiff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.tsindex 8320392bf..886bd28fc 100644--- a/ts/packages/core/test/models/toolRouter.test.ts+++ b/ts/packages/core/test/models/toolRouter.test.ts@@ -6,7 +6,11 @@ import { telemetry } from '../../src/telemetry/Telemetry';import { MockProvider } from '../utils/mocks/provider.mock';import { Tools } from '../../src/models/Tools';import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';-import { ToolRouterCreateSessionConfig, Session } from '../../src/types/toolRouter.types';+import {+ ToolRouterCreateSessionConfig,+ Session,+ SessionPreset,+} from '../../src/types/toolRouter.types';import { createCustomTool } from '../../src/models/CustomTool';import { DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX } from '../../src/models/ToolRouterSession';@@ -36,6 +40,7 @@ const createMockClient = () => ({session: {create: vi.fn(),retrieve: vi.fn(),+ attach: vi.fn(),link: vi.fn(),toolkits: vi.fn(),search: vi.fn(),@@ -162,6 +167,8 @@ describe('ToolRouter', () => {provider: mockProvider,apiKey: 'test-api-key',});+ mockClient.toolRouter.session.retrieve.mockResolvedValue(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.attach.mockResolvedValue(mockSessionRetrieveResponse);});describe('constructor', () => {@@ -323,7 +330,7 @@ describe('ToolRouter', () => {});const session = await toolRouter.create(userId, {- sessionPreset: 'direct_tools',+ sessionPreset: SessionPreset.DIRECT_TOOLS,toolkits: ['github'],});@@ -356,7 +363,7 @@ describe('ToolRouter', () => {});const session = await toolRouter.create(userId, {- sessionPreset: 'direct_tools',+ sessionPreset: SessionPreset.DIRECT_TOOLS,toolkits: ['github'],manageConnections: true,workbench: { enable: true },@@ -408,7 +415,7 @@ describe('ToolRouter', () => {});await toolRouter.create(userId, {- sessionPreset: 'direct_tools',+ sessionPreset: SessionPreset.DIRECT_TOOLS,toolkits: ['github'],preload: { tools: ['GITHUB_CREATE_ISSUE'] },experimental: { customTools: [grepTool] },@@ -2919,16 +2926,15 @@ describe('ToolRouter', () => {describe('use method', () => {const sessionId = 'session_123';- const attachEndpoint = (id: string) =>- `/api/v3.1/tool_router/session/${encodeURIComponent(id)}/attach`;- it('should attach an existing session by ID', async () => {- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ it('should retrieve an existing session by ID', async () => {+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);const session = await toolRouter.use(sessionId);- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), { body: {} });- expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId);+ expect(mockClient.toolRouter.session.attach).not.toHaveBeenCalled();+ expect(mockClient.post).not.toHaveBeenCalled();expect(session).toHaveProperty('sessionId', 'session_123');expect(session).toHaveProperty('mcp');expect(session.mcp).toEqual({@@ -2953,7 +2959,7 @@ describe('ToolRouter', () => {execute: vi.fn(async () => ({ matches: [] })),});- mockClient.post.mockResolvedValueOnce({+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({...mockSessionRetrieveResponse,experimental: {custom_tools: [@@ -2968,16 +2974,15 @@ describe('ToolRouter', () => {const session = await toolRouter.use(sessionId, { customTools: [grepTool] });- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), {- body: {- experimental: {- custom_tools: [expect.objectContaining({ slug: 'GREP' })],- },+ expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(sessionId, {+ experimental: {+ custom_tools: [expect.objectContaining({ slug: 'GREP' })],},});- expect(mockClient.post.mock.calls[0][1].body.experimental).not.toHaveProperty(+ expect(mockClient.toolRouter.session.attach.mock.calls[0][1].experimental).not.toHaveProperty('custom_toolkits');+ expect(mockClient.post).not.toHaveBeenCalled();expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();expect(session.customTools()).toEqual([expect.objectContaining({@@ -2996,7 +3001,7 @@ describe('ToolRouter', () => {},};- mockClient.post.mockResolvedValueOnce(customResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);const session = await toolRouter.use(sessionId);@@ -3006,7 +3011,7 @@ describe('ToolRouter', () => {});it('should return a session with working tools function', async () => {- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);const session = await toolRouter.use(sessionId);@@ -3025,7 +3030,7 @@ describe('ToolRouter', () => {});it('should return a session with working authorize function', async () => {- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);const session = await toolRouter.use(sessionId);@@ -3040,7 +3045,7 @@ describe('ToolRouter', () => {});it('should return a session with working toolkits function', async () => {- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);const session = await toolRouter.use(sessionId);@@ -3057,6 +3062,100 @@ describe('ToolRouter', () => {expect(toolkitsResult.items[0].slug).toBe('gmail');});+ it('should attach custom tools and expose SDK-preloaded custom schemas', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ preload: true,+ inputParams: z.object({ pattern: z.string() }),+ execute: vi.fn(async () => ({ matches: [] })),+ });+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({+ ...mockSessionRetrieveResponse,+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],+ experimental: {+ custom_tools: [+ {+ slug: 'LOCAL_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');++ const session = await toolRouter.use(sessionId, { customTools: [grepTool] });+ await session.tools();++ expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(sessionId, {+ experimental: {+ custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],+ },+ });+ expect(mockClient.post).not.toHaveBeenCalled();+ expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();+ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);+ });++ it('should apply preload all from an attached session to custom tools in use()', async () => {+ const grepTool = createCustomTool('GREP', {+ name: 'Grep',+ description: 'Search local text',+ inputParams: z.object({ pattern: z.string() }),+ execute: vi.fn(async () => ({ matches: [] })),+ });+ mockClient.toolRouter.session.attach.mockResolvedValueOnce({+ ...mockSessionRetrieveResponse,+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],+ config: {+ ...mockSessionRetrieveResponse.config,+ preload: { tools: 'all' },+ },+ experimental: {+ custom_tools: [+ {+ slug: 'LOCAL_GREP',+ original_slug: 'GREP',+ extends_toolkit: null,+ },+ ],+ },+ });+ mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');+ mockClient.toolRouter.session.search.mockResolvedValueOnce({+ success: true,+ error: null,+ results: [],+ tool_schemas: {},+ toolkit_connection_statuses: [],+ next_steps_guidance: [],+ session: {+ id: sessionId,+ generate_id: false,+ instructions: 'Reuse session',+ },+ time_info: {+ current_time_utc: '2025-03-09T12:00:00.000Z',+ current_time_utc_epoch_seconds: 1741521600,+ message: 'UTC',+ },+ });++ const session = await toolRouter.use(sessionId, { customTools: [grepTool] });+ await session.tools();+ await session.search({ query: 'search local text' });++ const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;+ expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);+ expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(sessionId, {+ queries: [{ use_case: 'search local text' }],+ experimental: {+ custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],+ },+ });+ });it('should handle different session IDs', async () => {const session1Response = {...mockSessionRetrieveResponse,@@ -3068,7 +3167,7 @@ describe('ToolRouter', () => {session_id: 'session_2',};- mockClient.post+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(session1Response).mockResolvedValueOnce(session2Response);@@ -3077,13 +3176,14 @@ describe('ToolRouter', () => {expect(session1.sessionId).toBe('session_1');expect(session2.sessionId).toBe('session_2');- expect(mockClient.post).toHaveBeenCalledTimes(2);- expect(mockClient.post).toHaveBeenNthCalledWith(1, attachEndpoint('session_1'), { body: {} });- expect(mockClient.post).toHaveBeenNthCalledWith(2, attachEndpoint('session_2'), { body: {} });+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(2);+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(1, 'session_1');+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(2, 'session_2');+ expect(mockClient.post).not.toHaveBeenCalled();});it('should handle MCP server type correctly', async () => {- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);const session = await toolRouter.use(sessionId);@@ -3091,21 +3191,22 @@ describe('ToolRouter', () => {expect(session.mcp.url).toBe('https://mcp.example.com/session_123');});- it('should throw error if session attach fails', async () => {+ it('should throw error if session retrieve fails', async () => {const error = new Error('Session not found');- mockClient.post.mockRejectedValueOnce(error);+ mockClient.toolRouter.session.retrieve.mockRejectedValueOnce(error);await expect(toolRouter.use(sessionId)).rejects.toThrow('Session not found');- expect(mockClient.post).toHaveBeenCalledWith(attachEndpoint(sessionId), { body: {} });+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId);+ expect(mockClient.post).not.toHaveBeenCalled();});- it('should handle attach with different tool lists', async () => {+ it('should handle retrieve with different tool lists', async () => {const customResponse = {...mockSessionRetrieveResponse,tool_router_tools: ['CUSTOM_TOOL_1', 'CUSTOM_TOOL_2'],};- mockClient.post.mockResolvedValueOnce(customResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);const session = await toolRouter.use(sessionId);@@ -3115,7 +3216,7 @@ describe('ToolRouter', () => {it('should be independent from create method', async () => {mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);- mockClient.post.mockResolvedValueOnce(mockSessionRetrieveResponse);+ mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);// Create a new sessionconst createdSession = await toolRouter.create('user_123');@@ -3127,8 +3228,8 @@ describe('ToolRouter', () => {// Both should have been called onceexpect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);- expect(mockClient.post).toHaveBeenCalledTimes(1);- expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();+ expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(1);+ expect(mockClient.post).not.toHaveBeenCalled();});});});