Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Refine ToolRouter preload docs and constants

Dhawal Upadhyaybccd32beaef0
diff --git a/.changeset/toolrouter-direct-tools-preset.md b/.changeset/toolrouter-direct-tools-preset.md
new file mode 100644
index 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.md
new file mode 100644
index 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__.py
index 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_TOOLS
from .core.models.tool_router_session_files import RemoteFile
from .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__.py
index 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 MCP
from .tool_router import ToolRouter
+from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
from .tool_router_session import ToolRouterSession
from .tool_router_session_files import RemoteFile, ToolRouterSessionFilesMount
from .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.py
index 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_ALL
if 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:
return
if 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 None
and (
normalized in custom_tools_map.by_original_slug
diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.py
index 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 t
from dataclasses import dataclass, field
import typing_extensions as te
+from composio_client.types.tool_router import session_create_params
from pydantic import BaseModel
from 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: bool
class 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: bool
diff --git a/python/composio/core/models/inline_custom_tools_payload.py b/python/composio/core/models/inline_custom_tools_payload.py
index 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 t
from composio_client import Omit, omit
from 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.py
index 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 Enum
import typing_extensions as te
from composio_client import omit
from 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 HttpClient
from 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, TToolCollection
from 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, preload
return (
False if manage_connections is None else manage_connections,
{"enable": False} if workbench is None else workbench,
- {"tools": "all"} if preload is None else preload,
+ {"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 configuration
session = 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_TOOLS
manage_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 config
manage_connections = (
@@ -884,12 +944,10 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
# experimental.assistive_prompt_config.user_timezone
custom_tools: t.Optional[t.List[CustomTool]] = None
custom_toolkits: t.Optional[t.List[ExperimentalToolkit]] = None
- local_custom_tools_map: t.Optional[CustomToolsMap] = None
inline_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 backend
custom_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_payload
if 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] = None
user_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.py
new file mode 100644
index 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.py
index 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 = 5
diff --git a/python/examples/tool_router/direct_tools_preset.py b/python/examples/tool_router/direct_tools_preset.py
index 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 os
from agents import Agent, Runner
from composio_openai_agents import OpenAIAgentsProvider
+from pydantic import BaseModel, Field
-from composio import Composio
+from composio import Composio, SESSION_PRESET_DIRECT_TOOLS
def 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.py
index 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.py
index 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, patch
import pytest
from composio_client import omit
from pydantic import BaseModel, Field
-from composio_client.types.tool_router.session_retrieve_response import (
- SessionRetrieveResponse,
-)
from composio.exceptions import ValidationError
from composio.core.models.custom_tool import ExperimentalAPI
from 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_response
client.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 response
mock_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_value
mock_response.experimental = MagicMock()
mock_response.experimental.assistive_prompt = None
mock_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_response
session = tool_router.use(session_id="session_456")
@@ -1024,8 +1129,10 @@ class TestToolRouter:
assert session.mcp.type == ToolRouterMCPServerType.HTTP
def 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 = None
mock_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 session
created_session = tool_router.create(user_id="user_123")
@@ -1452,12 +1559,10 @@ class TestToolRouter:
# Verify both methods were called
mock_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.md
index 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.
## Setup
1. **Install dependencies:**
+
```bash
pnpm install
```
2. **Configure environment:**
+
```bash
cp .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
## Customization
Edit `src/index.ts` to:
+
- Add specific apps you want to integrate with
- Implement your business logic
- Add error handling and logging
diff --git a/ts/examples/tool-router/src/direct-tools-preset.ts b/ts/examples/tool-router/src/direct-tools-preset.ts
index 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.ts
index 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.ts
index 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 session
diff --git a/ts/packages/core/src/lib/toolRouterConstants.ts b/ts/packages/core/src/lib/toolRouterConstants.ts
new file mode 100644
index 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.ts
index 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.ts
index 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 | SessionRetrieveResp
return 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 config
const 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 backend
const 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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 = z
preload: 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 behavior
diff --git a/ts/packages/core/test/models/toolRouter.test.ts b/ts/packages/core/test/models/toolRouter.test.ts
index 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 session
const createdSession = await toolRouter.create('user_123');
@@ -3127,8 +3228,8 @@ describe('ToolRouter', () => {
// Both should have been called once
expect(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();
});
});
});