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
fix(sdk): qualify custom toolkit child slug mapping across Python and TypeScript (#4311)
CoralGarden527420927183a2
diff --git a/.changeset/custom-toolkit-slug-mapping.md b/.changeset/custom-toolkit-slug-mapping.mdnew file mode 100644index 000000000..ff1ec5d93--- /dev/null+++ b/.changeset/custom-toolkit-slug-mapping.md@@ -0,0 +1,5 @@+---+'@composio/core': patch+---++Fix custom toolkit child slug mapping: reject response tools that have local handles but no exact toolkit match instead of silently dropping them or binding another toolkit's handler, derive bare-slug ambiguity from local definitions, and only reuse a same-toolkit bare alias in customToolkits().diff --git a/docs/content/reference/sdk-reference/python/session.mdx b/docs/content/reference/sdk-reference/python/session.mdxindex 9e6bf96f2..82f3f73cc 100644--- a/docs/content/reference/sdk-reference/python/session.mdx+++ b/docs/content/reference/sdk-reference/python/session.mdx@@ -103,7 +103,7 @@ def search(query: str, model: str | None = ...) -> SessionSearchResponse### execute()-Execute a tool within the session. For custom tools, accepts the original slug (e.g. "GREP") or the full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process; remote tools are sent to the Composio backend.+Execute a tool within the session. For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the original slug (e.g. "GREP") when that original slug is unique across the session's custom tools and toolkits. Custom tools are executed in-process; remote tools are sent to the Composio backend.```pythondef execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str | None = ...) -> SessionExecuteResponsediff --git a/docs/content/reference/sdk-reference/typescript/session.mdx b/docs/content/reference/sdk-reference/typescript/session.mdxindex 8f1727e2c..ff34635a8 100644--- a/docs/content/reference/sdk-reference/typescript/session.mdx+++ b/docs/content/reference/sdk-reference/typescript/session.mdx@@ -114,9 +114,10 @@ async delete(requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionExecute a tool within the session.-For custom tools, accepts the original slug (e.g. "GREP") or the-full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process;-remote tools are sent to the Composio backend.+For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the+original slug (e.g. "GREP") when that original slug is unique across+the session's custom tools and toolkits. Custom tools are executed+in-process; remote tools are sent to the Composio backend.```typescriptasync execute(toolSlug: string, arguments_?: Record<string, unknown>, options?: ToolRouterSessionExecuteOptions, requestOptions?: ComposioRequestOptions): Promise<ToolRouterSessionExecuteResponse>diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 584b25e41..929189f5d 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -138,6 +138,51 @@ def _build_final_slug(tool_slug: str, toolkit_slug: t.Optional[str] = None) -> sreturn f"{LOCAL_TOOL_PREFIX}{upper}"+def _qualified_original_slug_key(toolkit: t.Optional[str], original_slug: str) -> str:+ return f"{toolkit.upper() if toolkit else ''}::{original_slug.upper()}"+++def _can_share_original_slug(+ existing: CustomToolsMapEntry, next_entry: CustomToolsMapEntry+) -> bool:+ return (+ existing.toolkit is not None+ and next_entry.toolkit is not None+ and existing.toolkit.lower() != next_entry.toolkit.lower()+ )+++def _add_original_slug_alias(+ *,+ by_original_slug: t.Dict[str, CustomToolsMapEntry],+ ambiguous_original_slugs: t.Set[str],+ original_slug: str,+ entry: CustomToolsMapEntry,+) -> None:+ original_slug_key = original_slug.upper()+ if original_slug_key in ambiguous_original_slugs:+ return++ existing = by_original_slug.get(original_slug_key)+ if existing is None:+ by_original_slug[original_slug_key] = entry+ return++ if existing.final_slug.upper() == entry.final_slug.upper():+ return++ if _can_share_original_slug(existing, entry):+ del by_original_slug[original_slug_key]+ ambiguous_original_slugs.add(original_slug_key)+ return++ raise ValidationError(+ f'Custom tool slug collision: original slug "{original_slug}" '+ f'maps to multiple final slugs. "{existing.final_slug}" and '+ f'"{entry.final_slug}" both resolve from "{original_slug_key}".'+ )++def _get_input_json_schema(model: t.Type[BaseModel]) -> t.Dict[str, t.Any]:"""Convert a Pydantic model class to a JSON Schema dict suitable for the backend."""full_schema = model.model_json_schema()@@ -578,6 +623,8 @@ def build_custom_tools_map("""Build a CustomToolsMap from custom tools and toolkits."""by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}+ by_toolkit_and_original_slug: t.Dict[str, CustomToolsMapEntry] = {}+ ambiguous_original_slugs: t.Set[str] = set()def add_entry(handle: CustomTool, final_slug: str, toolkit: t.Optional[str]@@ -597,20 +644,24 @@ def build_custom_tools_map(f'Custom tool slug collision: "{final_slug}" is already registered.')- if original_slug in by_original_slug:- existing = by_original_slug[original_slug]+ qualified_key = _qualified_original_slug_key(toolkit, original_slug)+ if qualified_key in by_toolkit_and_original_slug:raise ValidationError(f'Custom tool slug collision: original slug "{handle.slug}" '- f"maps to multiple final slugs. "- f'"{existing.final_slug}" and "{final_slug}" both resolve '- f'from "{original_slug}".'+ f'is already registered for toolkit "{toolkit or "custom"}".')entry = CustomToolsMapEntry(handle=handle, final_slug=final_slug, toolkit=toolkit)by_final_slug[final_slug_key] = entry- by_original_slug[original_slug] = entry+ by_toolkit_and_original_slug[qualified_key] = entry+ _add_original_slug_alias(+ by_original_slug=by_original_slug,+ ambiguous_original_slugs=ambiguous_original_slugs,+ original_slug=original_slug,+ entry=entry,+ )# Process standalone toolsfor handle in tools:@@ -629,6 +680,8 @@ def build_custom_tools_map(return CustomToolsMap(by_final_slug=by_final_slug,by_original_slug=by_original_slug,+ by_toolkit_and_original_slug=by_toolkit_and_original_slug,+ ambiguous_original_slugs=ambiguous_original_slugs,toolkits=list(toolkits) if toolkits else None,tools=list(tools) if tools else None,)@@ -648,41 +701,94 @@ def build_custom_tools_map_from_response("""Build a CustomToolsMap using the slug/original_slug mapping from the backend response."""by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}+ by_toolkit_and_original_slug: t.Dict[str, CustomToolsMapEntry] = {}+ ambiguous_original_slugs: t.Set[str] = set()++ # Build lookups from toolkit + original slug and from original slug -> matches.+ handles_by_qualified_original: t.Dict[+ str, t.Tuple[CustomTool, t.Optional[str]]+ ] = {}+ handles_by_original: t.Dict[str, t.List[t.Tuple[CustomTool, t.Optional[str]]]] = {}++ def register_handle(handle: CustomTool, toolkit: t.Optional[str]) -> None:+ original_slug = handle.slug.upper()+ match = (handle, toolkit)+ handles_by_qualified_original[+ _qualified_original_slug_key(toolkit, original_slug)+ ] = match+ handles_by_original.setdefault(original_slug, []).append(match)- # Build lookup from original slug -> handle + toolkit- handles_by_original: t.Dict[str, t.Tuple[CustomTool, t.Optional[str]]] = {}for handle in tools:- key = handle.slug.upper()- if key in handles_by_original:- raise ValidationError(- f'Duplicate custom tool slug "{handle.slug}" — '- f"each tool must have a unique slug across all custom tools and toolkits."- )- handles_by_original[key] = (handle, handle.extends_toolkit)+ register_handle(handle, handle.extends_toolkit)if toolkits:for tk in toolkits:for handle in tk.tools:- key = handle.slug.upper()- if key in handles_by_original:- raise ValidationError(- f'Duplicate custom tool slug "{handle.slug}" — '- f"each tool must have a unique slug across all custom tools and toolkits."- )- handles_by_original[key] = (handle, tk.slug)+ register_handle(handle, tk.slug)++ def find_handle(+ final_slug: str, original_slug: str, toolkit: t.Optional[str]+ ) -> t.Optional[t.Tuple[CustomTool, t.Optional[str]]]:+ original_slug_key = original_slug.upper()+ qualified_match = handles_by_qualified_original.get(+ _qualified_original_slug_key(toolkit, original_slug_key)+ )+ if qualified_match is not None:+ return qualified_match++ bare_matches = handles_by_original.get(original_slug_key, [])+ if not bare_matches:+ # Response tool not defined locally; nothing to route in-process.+ return None+ # A bare match may only stand in when the response carries no toolkit+ # identity. Binding a toolkit child to another toolkit's handler would+ # silently execute the wrong implementation.+ if toolkit is None and len(bare_matches) == 1:+ return bare_matches[0]++ registered = sorted(+ {(match_toolkit or "custom").upper() for _, match_toolkit in bare_matches}+ )+ raise ValidationError(+ f'Cannot map custom tool "{final_slug}": original slug '+ f'"{original_slug}" for toolkit "{toolkit or "custom"}" has no exact '+ f"local match. Registered for toolkits: {', '.join(registered)}."+ )def add_entry(final_slug: str, original_slug: str, toolkit: t.Optional[str]) -> None:- match = handles_by_original.get(original_slug.upper())+ resolved_toolkit = toolkit+ match = find_handle(final_slug, original_slug, resolved_toolkit)if not match:returnhandle, default_toolkit = match- resolved_toolkit = toolkit if toolkit is not None else default_toolkit+ if resolved_toolkit is None:+ resolved_toolkit = default_toolkit++ final_slug_key = final_slug.upper()+ if final_slug_key in by_final_slug:+ raise ValidationError(+ f'Custom tool slug collision: "{final_slug}" is already registered.'+ )++ qualified_key = _qualified_original_slug_key(resolved_toolkit, original_slug)+ if qualified_key in by_toolkit_and_original_slug:+ raise ValidationError(+ f'Custom tool slug collision: original slug "{handle.slug}" '+ f'is already registered for toolkit "{resolved_toolkit or "custom"}".'+ )+entry = CustomToolsMapEntry(handle=handle, final_slug=final_slug, toolkit=resolved_toolkit)- by_final_slug[final_slug.upper()] = entry- by_original_slug[original_slug.upper()] = entry+ by_final_slug[final_slug_key] = entry+ by_toolkit_and_original_slug[qualified_key] = entry+ _add_original_slug_alias(+ by_original_slug=by_original_slug,+ ambiguous_original_slugs=ambiguous_original_slugs,+ original_slug=original_slug,+ entry=entry,+ )if experimental and experimental.custom_tools:for ct in experimental.custom_tools:@@ -693,9 +799,19 @@ def build_custom_tools_map_from_response(for ctk_tool in ctk.tools:add_entry(ctk_tool.slug, ctk_tool.original_slug, ctk.slug)+ # Ambiguity follows the local definitions, not whichever subset the+ # response happened to include: a shared child slug must never become+ # callable by its bare name just because a sibling was omitted.+ for original_slug_key, matches in handles_by_original.items():+ if len(matches) > 1:+ by_original_slug.pop(original_slug_key, None)+ ambiguous_original_slugs.add(original_slug_key)+return CustomToolsMap(by_final_slug=by_final_slug,by_original_slug=by_original_slug,+ by_toolkit_and_original_slug=by_toolkit_and_original_slug,+ ambiguous_original_slugs=ambiguous_original_slugs,toolkits=list(toolkits) if toolkits else None,tools=list(tools) if tools else None,)@@ -711,6 +827,19 @@ def find_custom_tool_map_entry_by_final_slug(return custom_tools_map.by_final_slug.get(slug.upper())+def find_custom_tool_map_entry_by_toolkit_and_original_slug(+ custom_tools_map: t.Optional[CustomToolsMap],+ toolkit: t.Optional[str],+ slug: str,+) -> t.Optional[CustomToolsMapEntry]:+ """Find a custom toolkit tool by toolkit slug and original tool slug."""+ if custom_tools_map is None:+ return None+ return custom_tools_map.by_toolkit_and_original_slug.get(+ _qualified_original_slug_key(toolkit, slug)+ )++def assert_no_custom_tool_slugs_in_preload(preload_tools: t.Union[t.Sequence[str], t.Literal["all"], None],custom_tools_map: t.Optional[CustomToolsMap],@@ -734,6 +863,7 @@ def assert_no_custom_tool_slugs_in_preload(custom_tools_map is not Noneand (normalized in custom_tools_map.by_original_slug+ or normalized in custom_tools_map.ambiguous_original_slugsor normalized in custom_tools_map.by_final_slug)):diff --git a/python/composio/core/models/custom_tool_execution.py b/python/composio/core/models/custom_tool_execution.pyindex 6df6bd74e..20a04f4ba 100644--- a/python/composio/core/models/custom_tool_execution.py+++ b/python/composio/core/models/custom_tool_execution.py@@ -17,6 +17,8 @@ import typing as tfrom pydantic import ValidationError as PydanticValidationError+from composio.exceptions import ValidationError+from .custom_tool_types import (CustomToolsMap,CustomToolsMapEntry,@@ -37,7 +39,37 @@ def find_custom_tool(if map_ is None:return Noneupper = slug.upper()- return map_.by_final_slug.get(upper) or map_.by_original_slug.get(upper)+ final_slug_match = map_.by_final_slug.get(upper)+ if final_slug_match is not None:+ return final_slug_match+ if upper in map_.ambiguous_original_slugs:+ return None+ return map_.by_original_slug.get(upper)+++def assert_unambiguous_custom_tool_slug(+ map_: t.Optional[CustomToolsMap], slug: str+) -> None:+ """Reject ambiguous bare original slugs before remote fallback."""+ if map_ is None:+ return++ upper = slug.upper()+ if upper not in map_.ambiguous_original_slugs:+ return++ final_slugs = sorted(+ entry.final_slug+ for entry in map_.by_final_slug.values()+ if entry.handle.slug.upper() == upper+ )+ hint = f" Use one of: {', '.join(final_slugs)}." if final_slugs else ""+ raise ValidationError(+ f'Ambiguous custom tool slug "{slug}". Multiple custom toolkit tools '+ "share this original slug; manual session.execute() by original slug "+ "is only supported when the original slug is unique."+ f"{hint}"+ )def execute_custom_tool(diff --git a/python/composio/core/models/custom_tool_types.py b/python/composio/core/models/custom_tool_types.pyindex 21d754f00..f00a8e234 100644--- a/python/composio/core/models/custom_tool_types.py+++ b/python/composio/core/models/custom_tool_types.py@@ -175,9 +175,16 @@ class CustomToolsMap:"""Lookup maps used by ToolRouterSession for routing custom tools."""by_final_slug: t.Dict[str, CustomToolsMapEntry] = field(default_factory=dict)+ # Bare original slugs are only stored here when they resolve uniquely.by_original_slug: t.Dict[str, CustomToolsMapEntry] = field(default_factory=dict)toolkits: t.Optional[t.List[t.Any]] = Nonetools: t.Optional[t.List["CustomTool"]] = None+ # Toolkit-qualified lookup allows different custom toolkits to reuse a child slug.+ by_toolkit_and_original_slug: t.Dict[str, CustomToolsMapEntry] = field(+ default_factory=dict+ )+ # Bare original slugs in this set must be addressed by their final slug.+ ambiguous_original_slugs: t.Set[str] = field(default_factory=set)# ────────────────────────────────────────────────────────────────diff --git a/python/composio/core/models/session_context.py b/python/composio/core/models/session_context.pyindex f90280b67..7d333c983 100644--- a/python/composio/core/models/session_context.py+++ b/python/composio/core/models/session_context.py@@ -15,6 +15,7 @@ from composio_client.types.tool_router.session_execute_response import ()from composio.client import HttpClientfrom composio.core.models.custom_tool_execution import (+ assert_unambiguous_custom_tool_slug,execute_custom_tool,find_custom_tool,)@@ -159,6 +160,8 @@ class SessionContextImpl:log_id="",)+ assert_unambiguous_custom_tool_slug(self._custom_tools_map, tool_slug)+# Serialize any Pydantic model instances before sending to remote APIserialized = _serialize_arguments(arguments)diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.pyindex e25e8f8c8..6f1f5cb1d 100644--- a/python/composio/core/models/tool_router_session.py+++ b/python/composio/core/models/tool_router_session.py@@ -32,8 +32,12 @@ from composio.client import HttpClientfrom composio.client.types import Toolfrom composio.core.models._modifiers import Modifiers, apply_modifier_by_typefrom composio.core.models.connected_accounts import ConnectionRequest-from composio.core.models.custom_tool import find_custom_tool_map_entry_by_final_slug+from composio.core.models.custom_tool import (+ find_custom_tool_map_entry_by_final_slug,+ find_custom_tool_map_entry_by_toolkit_and_original_slug,+)from composio.core.models.custom_tool_execution import (+ assert_unambiguous_custom_tool_slug,execute_custom_tool,find_custom_tool,)@@ -388,6 +392,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):t.cast(SessionContextImpl, self._session_context),),)+ assert_unambiguous_custom_tool_slug(self._custom_tools_map, slug)# Non-multi-execute meta tools always go to backendreturn backend_execute(slug, arguments)@@ -434,6 +439,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):if entry:local_items.append((i, entry))else:+ assert_unambiguous_custom_tool_slug(+ self._custom_tools_map, p["tool_slug"]+ )remote_indices.append(i)# All remote — just forward entire payload (no modifiers — caller handles them)@@ -706,9 +714,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):"""Execute a tool within the session.- For custom tools, accepts the original slug (e.g. "GREP") or the- full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process;- remote tools are sent to the Composio backend.+ For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the+ original slug (e.g. "GREP") when that original slug is unique across+ the session's custom tools and toolkits. Custom tools are executed+ in-process; remote tools are sent to the Composio backend.:param account: Account ID or alias for direct app tool execution inmulti-account sessions. Helper/meta tools either ignore this@@ -731,6 +740,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):log_id="",)+ assert_unambiguous_custom_tool_slug(self._custom_tools_map, tool_slug)+return self._client.tool_router.session.execute(session_id=self.session_id,tool_slug=tool_slug,@@ -784,7 +795,20 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):for tk in self._custom_tools_map.toolkits:tools = []for tool in tk.tools:- entry = self._custom_tools_map.by_original_slug.get(tool.slug.upper())+ entry = find_custom_tool_map_entry_by_toolkit_and_original_slug(+ self._custom_tools_map, tk.slug, tool.slug+ )+ if entry is None:+ # Only trust a bare alias that belongs to this toolkit.+ bare = self._custom_tools_map.by_original_slug.get(+ tool.slug.upper()+ )+ if (+ bare is not None+ and bare.toolkit is not None+ and bare.toolkit.lower() == tk.slug.lower()+ ):+ entry = baretools.append(RegisteredCustomTool(slug=entry.final_slug if entry else tool.slug,diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.pyindex 853e77af7..9ae01d3c9 100644--- a/python/tests/test_custom_tools.py+++ b/python/tests/test_custom_tools.py@@ -28,12 +28,14 @@ from pydantic import BaseModel, Fieldfrom composio.core.models.custom_tool import (ExperimentalToolkit,+ assert_no_custom_tool_slugs_in_preload,build_custom_tools_map,build_custom_tools_map_from_response,serialize_custom_toolkits,serialize_custom_tools,)from composio.core.models.custom_tool_execution import (+ assert_unambiguous_custom_tool_slug,execute_custom_tool,find_custom_tool,)@@ -74,6 +76,21 @@ def grep_tool():return grep+def duplicate_slug_tools():+ @exp.tool(slug="GREP")+ def alpha_grep(input: GrepInput, ctx):+ """Search Alpha."""+ return {"toolkit": "alpha", "matches": [input.pattern]}++ @exp.tool(slug="GREP")+ def beta_grep(input: GrepInput, ctx):+ """Search Beta."""+ return {"toolkit": "beta", "matches": [input.pattern]}++ return alpha_grep, beta_grep++@pytest.fixturedef email_tool():@exp.tool(extends_toolkit="gmail")@@ -459,10 +476,62 @@ class TestCustomToolsMap:m = build_custom_tools_map([], [role_toolkit])assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug+ def test_allows_same_slug_in_different_toolkits(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)++ m = build_custom_tools_map([], [alpha, beta])++ assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP", "LOCAL_BETA_GREP"}+ assert "GREP" not in m.by_original_slug+ assert m.ambiguous_original_slugs == {"GREP"}++ def test_ambiguous_original_slug_requires_final_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ m = build_custom_tools_map([], [alpha, beta])++ assert find_custom_tool(m, "LOCAL_ALPHA_GREP").toolkit == "ALPHA"+ assert find_custom_tool(m, "LOCAL_BETA_GREP").toolkit == "BETA"+ assert find_custom_tool(m, "GREP") is None+ with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):+ assert_unambiguous_custom_tool_slug(m, "GREP")++ def test_preload_rejects_ambiguous_original_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ m = build_custom_tools_map([], [alpha, beta])++ with pytest.raises(ValidationError, match="not supported in preload.tools"):+ assert_no_custom_tool_slugs_in_preload(["grep"], m)+def test_collision_detection(self, grep_tool):with pytest.raises(ValidationError, match="collision"):build_custom_tools_map([grep_tool, grep_tool])+ def test_rejects_standalone_and_toolkit_same_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)++ with pytest.raises(ValidationError, match="collision"):+ build_custom_tools_map([alpha_tool], [beta])+class TestFindCustomTool:def test_find_by_final_slug(self, grep_tool):@@ -506,6 +575,138 @@ class TestBuildMapFromResponse:assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slugassert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug+ def test_allows_same_slug_in_different_toolkits(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="ALPHA",+ tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],+ ),+ MagicMock(+ slug="BETA",+ tools=[MagicMock(slug="LOCAL_BETA_GREP", original_slug="GREP")],+ ),+ ]++ m = build_custom_tools_map_from_response([], [alpha, beta], mock_exp)++ assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP", "LOCAL_BETA_GREP"}+ assert m.by_final_slug["LOCAL_ALPHA_GREP"].toolkit == "ALPHA"+ assert m.by_final_slug["LOCAL_BETA_GREP"].toolkit == "BETA"+ assert m.ambiguous_original_slugs == {"GREP"}++ def _duplicate_toolkits(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ return alpha, beta++ def test_rejects_toolkit_child_without_exact_match(self, duplicate_slug_tools):+ alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="GAMMA",+ tools=[MagicMock(slug="LOCAL_GAMMA_GREP", original_slug="GREP")],+ ),+ ]++ with pytest.raises(ValidationError, match="no exact local match"):+ build_custom_tools_map_from_response([], [alpha, beta], mock_exp)++ def test_never_binds_toolkit_child_to_another_toolkit(self, duplicate_slug_tools):+ alpha_tool, _ = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="BETA",+ tools=[MagicMock(slug="LOCAL_BETA_GREP", original_slug="GREP")],+ ),+ ]++ with pytest.raises(ValidationError, match='for toolkit "BETA"'):+ build_custom_tools_map_from_response([], [alpha], mock_exp)++ def test_standalone_falls_back_to_unique_bare_match(self, email_tool):+ mock_exp = MagicMock()+ mock_exp.custom_tools = [+ MagicMock(+ slug="LOCAL_GMAIL_GET_EMAILS",+ original_slug="GET_EMAILS",+ extends_toolkit=None,+ )+ ]+ mock_exp.custom_toolkits = []++ m = build_custom_tools_map_from_response([email_tool], None, mock_exp)++ assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"++ def test_skips_response_tools_not_defined_locally(self, grep_tool):+ mock_exp = MagicMock()+ mock_exp.custom_tools = [+ MagicMock(slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None),+ MagicMock(slug="LOCAL_STALE", original_slug="STALE", extends_toolkit=None),+ ]+ mock_exp.custom_toolkits = []++ m = build_custom_tools_map_from_response([grep_tool], None, mock_exp)++ assert set(m.by_final_slug) == {"LOCAL_GREP"}++ def test_ambiguity_follows_local_definitions(self, duplicate_slug_tools):+ alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="ALPHA",+ tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],+ ),+ ]++ m = build_custom_tools_map_from_response([], [alpha, beta], mock_exp)++ assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP"}+ assert "GREP" not in m.by_original_slug+ assert m.ambiguous_original_slugs == {"GREP"}+ assert find_custom_tool(m, "GREP") is None++ def test_rejects_duplicate_qualified_response_entries(self, duplicate_slug_tools):+ alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="ALPHA",+ tools=[+ MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP"),+ MagicMock(slug="LOCAL_ALPHA_GREP_2", original_slug="GREP"),+ ],+ ),+ ]++ with pytest.raises(ValidationError, match="already registered for toolkit"):+ build_custom_tools_map_from_response([], [alpha, beta], mock_exp)+# ────────────────────────────────────────────────────────────────# Execution tests@@ -556,6 +757,27 @@ class TestSessionContextImpl:assert result.log_id == ""assert result.data["matches"] == ["test"]+ def test_sibling_routing_rejects_ambiguous_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ m = build_custom_tools_map([], [alpha, beta])+ mock_client = MagicMock()+ ctx = SessionContextImpl(+ client=mock_client, user_id="u", session_id="s", custom_tools_map=m+ )++ with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):+ ctx.execute("GREP", {"pattern": "x"})+ mock_client.tool_router.session.execute.assert_not_called()++ result = ctx.execute("LOCAL_BETA_GREP", {"pattern": "x"})+ assert result.data["toolkit"] == "beta"+def test_remote_fallback(self, grep_tool):m = build_custom_tools_map([grep_tool])mock_client = MagicMock()@@ -838,6 +1060,100 @@ class TestToolRouterSessionCustomTools:assert len(tks) == 1assert tks[0].slug == "ROLE_MANAGER"+ def test_custom_toolkits_list_uses_qualified_slugs(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ custom_tools_map = build_custom_tools_map([], [alpha, beta])+ s = ToolRouterSession(+ client=MagicMock(),+ provider=MagicMock(),+ dangerously_allow_auto_upload_download_files=True,+ session_id="s",+ mcp=MagicMock(),+ experimental=MagicMock(),+ custom_tools_map=custom_tools_map,+ user_id="u",+ )++ toolkits = s.custom_toolkits()++ assert [tk.tools[0].slug for tk in toolkits] == [+ "LOCAL_ALPHA_GREP",+ "LOCAL_BETA_GREP",+ ]++ def test_custom_toolkits_list_never_borrows_other_toolkit_slug(+ self, duplicate_slug_tools+ ):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ mock_exp = MagicMock()+ mock_exp.custom_tools = []+ mock_exp.custom_toolkits = [+ MagicMock(+ slug="ALPHA",+ tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],+ ),+ ]+ custom_tools_map = build_custom_tools_map_from_response(+ [], [alpha, beta], mock_exp+ )+ s = ToolRouterSession(+ client=MagicMock(),+ provider=MagicMock(),+ dangerously_allow_auto_upload_download_files=True,+ session_id="s",+ mcp=MagicMock(),+ experimental=MagicMock(),+ custom_tools_map=custom_tools_map,+ user_id="u",+ )++ assert [tk.tools[0].slug for tk in s.custom_toolkits()] == [+ "LOCAL_ALPHA_GREP",+ "GREP",+ ]++ def test_execute_rejects_ambiguous_original_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ custom_tools_map = build_custom_tools_map([], [alpha, beta])+ client = MagicMock()+ s = ToolRouterSession(+ client=client,+ provider=MagicMock(),+ dangerously_allow_auto_upload_download_files=True,+ session_id="s",+ mcp=MagicMock(),+ experimental=MagicMock(),+ custom_tools_map=custom_tools_map,+ user_id="u",+ )++ with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):+ s.execute("GREP", arguments={"pattern": "x"})+ client.tool_router.session.execute.assert_not_called()++ alpha_result = s.execute("LOCAL_ALPHA_GREP", arguments={"pattern": "x"})+ beta_result = s.execute("LOCAL_BETA_GREP", arguments={"pattern": "x"})+ assert alpha_result.data["toolkit"] == "alpha"+ assert beta_result.data["toolkit"] == "beta"+def test_empty_when_no_map(self):s = ToolRouterSession(client=MagicMock(),@@ -879,6 +1195,43 @@ class TestMultiExecuteRouting:assert result["successful"] is Trueassert result["data"]["matches"] == ["x"]+ def test_rejects_ambiguous_original_slug(self, duplicate_slug_tools):+ alpha_tool, beta_tool = duplicate_slug_tools+ alpha = ExperimentalToolkit(+ slug="ALPHA", name="Alpha", description="Alpha tools"+ )+ alpha._tools.append(alpha_tool)+ beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")+ beta._tools.append(beta_tool)+ s = ToolRouterSession(+ client=MagicMock(),+ provider=MagicMock(),+ dangerously_allow_auto_upload_download_files=True,+ session_id="s",+ mcp=MagicMock(),+ experimental=MagicMock(),+ custom_tools_map=build_custom_tools_map([], [alpha, beta]),+ user_id="u",+ )+ tm = MagicMock()+ backend = MagicMock()+ tm._wrap_execute_tool_for_tool_router.return_value = backend++ with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):+ s._route_multi_execute(+ {+ "tools": [+ {+ "tool_slug": "LOCAL_ALPHA_GREP",+ "arguments": {"pattern": "x"},+ },+ {"tool_slug": "GREP", "arguments": {"pattern": "x"}},+ ]+ },+ tm,+ )+ backend.assert_not_called()+def test_all_remote(self, grep_tool):s = self._make_session(grep_tool)tm = MagicMock()diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.tsindex 0dc6ecd68..63e61204c 100644--- a/ts/packages/core/src/models/CustomTool.ts+++ b/ts/packages/core/src/models/CustomTool.ts@@ -514,7 +514,11 @@ export function buildCustomToolsMapFromResponse(}}- const findHandle = (originalSlug: string, toolkit?: string): HandleMatch | undefined => {+ const findHandle = (+ finalSlug: string,+ originalSlug: string,+ toolkit?: string+ ): HandleMatch | undefined => {const originalSlugKey = originalSlug.toUpperCase();const qualifiedMatch = handlesByQualifiedOriginalSlug.get(qualifiedOriginalSlugKey(toolkit, originalSlugKey)@@ -522,13 +526,26 @@ export function buildCustomToolsMapFromResponse(if (qualifiedMatch) return qualifiedMatch;const bareMatches = handlesByOriginalSlug.get(originalSlugKey) ?? [];- return bareMatches.length === 1 ? bareMatches[0] : undefined;+ // Response tool not defined locally; nothing to route in-process.+ if (bareMatches.length === 0) return undefined;+ // A bare match may only stand in when the response carries no toolkit identity.+ // Binding a toolkit child to another toolkit's handler would silently execute+ // the wrong implementation.+ if (toolkit === undefined && bareMatches.length === 1) return bareMatches[0];++ const registered = [+ ...new Set(bareMatches.map(m => (m.toolkit ?? 'custom').toUpperCase())),+ ].sort();+ throw new ValidationError(+ `Cannot map custom tool "${finalSlug}": original slug "${originalSlug}" for toolkit ` ++ `"${toolkit ?? 'custom'}" has no exact local match. Registered for toolkits: ${registered.join(', ')}.`+ );};const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string | null) => {const resolvedToolkit = toolkit ?? undefined;- const match = findHandle(originalSlug, resolvedToolkit);- if (!match) return; // Response tool not found in our handles (shouldn't happen)+ const match = findHandle(finalSlug, originalSlug, resolvedToolkit);+ if (!match) return;const finalSlugKey = finalSlug.toUpperCase();if (byFinalSlug.has(finalSlugKey)) {@@ -537,13 +554,21 @@ export function buildCustomToolsMapFromResponse();}+ const entryToolkit = resolvedToolkit ?? match.toolkit;+ const qualifiedKey = qualifiedOriginalSlugKey(entryToolkit, originalSlug);+ if (byToolkitAndOriginalSlug.has(qualifiedKey)) {+ throw new ValidationError(+ `Custom tool slug collision: original slug "${match.handle.slug}" is already registered for toolkit "${entryToolkit ?? 'custom'}".`+ );+ }+const entry: CustomToolsMapEntry = {handle: match.handle,finalSlug,- toolkit: resolvedToolkit ?? match.toolkit,+ toolkit: entryToolkit,};byFinalSlug.set(finalSlugKey, entry);- byToolkitAndOriginalSlug.set(qualifiedOriginalSlugKey(entry.toolkit, originalSlug), entry);+ byToolkitAndOriginalSlug.set(qualifiedKey, entry);addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });};@@ -563,6 +588,16 @@ export function buildCustomToolsMapFromResponse(}}+ // Ambiguity follows the local definitions, not whichever subset the response+ // happened to include: a shared child slug must never become callable by its+ // bare name just because a sibling was omitted.+ for (const [originalSlugKey, matches] of handlesByOriginalSlug) {+ if (matches.length > 1) {+ byOriginalSlug.delete(originalSlugKey);+ ambiguousOriginalSlugs.add(originalSlugKey);+ }+ }+return {byFinalSlug,byOriginalSlug,diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex e8fdb9ac7..97f896d1b 100644--- a/ts/packages/core/src/models/ToolRouterSession.ts+++ b/ts/packages/core/src/models/ToolRouterSession.ts@@ -375,9 +375,13 @@ export class ToolRouterSession<tools: tk.tools.map(tool => {// Look up by toolkit + original slug so toolkits can safely reuse common names// like VERSION, CLICK, or SEARCH without losing the backend-assigned final slug.+ // Only trust a bare alias that belongs to this toolkit.+ const bare = this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());const entry =findCustomToolMapEntryByToolkitAndOriginalSlug(this.customToolsMap, tk.slug, tool.slug) ??- this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());+ (bare?.toolkit && bare.toolkit.toLowerCase() === tk.slug.toLowerCase()+ ? bare+ : undefined);return {slug: entry?.finalSlug ?? tool.slug,name: tool.name,@@ -555,9 +559,10 @@ export class ToolRouterSession</*** Execute a tool within the session.*- * For custom tools, accepts the original slug (e.g. "GREP") or the- * full slug (e.g. "LOCAL_GREP"). Custom tools are executed in-process;- * remote tools are sent to the Composio backend.+ * For custom tools, accepts the full slug (e.g. "LOCAL_GREP") or the+ * original slug (e.g. "GREP") when that original slug is unique across+ * the session's custom tools and toolkits. Custom tools are executed+ * in-process; remote tools are sent to the Composio backend.** @param toolSlug - The tool slug to execute* @param arguments_ - Optional tool argumentsdiff --git a/ts/packages/core/test/models/customTool.test.ts b/ts/packages/core/test/models/customTool.test.tsindex 464802038..e218de4da 100644--- a/ts/packages/core/test/models/customTool.test.ts+++ b/ts/packages/core/test/models/customTool.test.ts@@ -6,6 +6,7 @@ import {createCustomTool,createCustomToolkit,buildCustomToolsMap,+ buildCustomToolsMapFromResponse,serializeCustomTools,serializeCustomToolkits,LOCAL_TOOL_PREFIX,@@ -451,6 +452,27 @@ describe('buildCustomToolsMap', () => {expect(() => buildCustomToolsMap([standalone], [tk])).toThrow('collision');});++ it('should allow the same original slug in different toolkits and mark it ambiguous', () => {+ const alpha: CustomToolkit = {+ slug: 'ALPHA',+ name: 'Alpha',+ description: 'Alpha tools',+ tools: [makeTool('GREP')],+ };+ const beta: CustomToolkit = {+ slug: 'BETA',+ name: 'Beta',+ description: 'Beta tools',+ tools: [makeTool('GREP')],+ };++ const map = buildCustomToolsMap([], [alpha, beta]);++ expect([...map.byFinalSlug.keys()].sort()).toEqual(['LOCAL_ALPHA_GREP', 'LOCAL_BETA_GREP']);+ expect(map.byOriginalSlug.has('GREP')).toBe(false);+ expect(map.ambiguousOriginalSlugs).toEqual(new Set(['GREP']));+ });});describe('length validation', () => {@@ -505,6 +527,150 @@ describe('buildCustomToolsMap', () => {});});+// ────────────────────────────────────────────────────────────────+// buildCustomToolsMapFromResponse()+// ────────────────────────────────────────────────────────────────++describe('buildCustomToolsMapFromResponse', () => {+ const makeTool = (slug: string, extendsToolkit?: string): CustomTool => ({+ slug,+ name: `Tool ${slug}`,+ description: `Description for ${slug}`,+ extendsToolkit,+ inputSchema: { type: 'object', properties: {} },+ inputParams: z.object({}),+ execute: vi.fn(),+ });+ const makeToolkit = (slug: string, tools: CustomTool[]): CustomToolkit => ({+ slug,+ name: slug,+ description: `${slug} tools`,+ tools,+ });+ type ResponseExperimental = Parameters<typeof buildCustomToolsMapFromResponse>[2];+ const response = (value: {+ custom_tools: Array<{ slug: string; original_slug: string; extends_toolkit?: string }>;+ custom_toolkits: Array<{ slug: string; tools: Array<{ slug: string; original_slug: string }> }>;+ }): ResponseExperimental => value as unknown as ResponseExperimental;+ const alpha = makeToolkit('ALPHA', [makeTool('GREP')]);+ const beta = makeToolkit('BETA', [makeTool('GREP')]);++ it('maps shared child slugs by toolkit and keeps the bare slug ambiguous', () => {+ const map = buildCustomToolsMapFromResponse(+ [],+ [alpha, beta],+ response({+ custom_tools: [],+ custom_toolkits: [+ { slug: 'ALPHA', tools: [{ slug: 'LOCAL_ALPHA_GREP', original_slug: 'GREP' }] },+ { slug: 'BETA', tools: [{ slug: 'LOCAL_BETA_GREP', original_slug: 'GREP' }] },+ ],+ })+ );++ expect(map.byFinalSlug.get('LOCAL_ALPHA_GREP')?.toolkit).toBe('ALPHA');+ expect(map.byFinalSlug.get('LOCAL_BETA_GREP')?.toolkit).toBe('BETA');+ expect(map.ambiguousOriginalSlugs).toEqual(new Set(['GREP']));+ });++ it('rejects a toolkit child without an exact local match', () => {+ expect(() =>+ buildCustomToolsMapFromResponse(+ [],+ [alpha, beta],+ response({+ custom_tools: [],+ custom_toolkits: [+ { slug: 'GAMMA', tools: [{ slug: 'LOCAL_GAMMA_GREP', original_slug: 'GREP' }] },+ ],+ })+ )+ ).toThrow('no exact local match');+ });++ it('never binds a toolkit child to another toolkit handler', () => {+ expect(() =>+ buildCustomToolsMapFromResponse(+ [],+ [alpha],+ response({+ custom_tools: [],+ custom_toolkits: [+ { slug: 'BETA', tools: [{ slug: 'LOCAL_BETA_GREP', original_slug: 'GREP' }] },+ ],+ })+ )+ ).toThrow('for toolkit "BETA"');+ });++ it('falls back to a unique bare match for standalone tools without toolkit identity', () => {+ const map = buildCustomToolsMapFromResponse(+ [makeTool('GET_EMAILS', 'gmail')],+ undefined,+ response({+ custom_tools: [{ slug: 'LOCAL_GMAIL_GET_EMAILS', original_slug: 'GET_EMAILS' }],+ custom_toolkits: [],+ })+ );++ expect(map.byFinalSlug.get('LOCAL_GMAIL_GET_EMAILS')?.toolkit).toBe('gmail');+ });++ it('skips response tools that are not defined locally', () => {+ const map = buildCustomToolsMapFromResponse(+ [makeTool('GREP')],+ undefined,+ response({+ custom_tools: [+ { slug: 'LOCAL_GREP', original_slug: 'GREP' },+ { slug: 'LOCAL_STALE', original_slug: 'STALE' },+ ],+ custom_toolkits: [],+ })+ );++ expect([...map.byFinalSlug.keys()]).toEqual(['LOCAL_GREP']);+ });++ it('derives ambiguity from local definitions when the response omits a sibling', () => {+ const map = buildCustomToolsMapFromResponse(+ [],+ [alpha, beta],+ response({+ custom_tools: [],+ custom_toolkits: [+ { slug: 'ALPHA', tools: [{ slug: 'LOCAL_ALPHA_GREP', original_slug: 'GREP' }] },+ ],+ })+ );++ expect([...map.byFinalSlug.keys()]).toEqual(['LOCAL_ALPHA_GREP']);+ expect(map.byOriginalSlug.has('GREP')).toBe(false);+ expect(map.ambiguousOriginalSlugs).toEqual(new Set(['GREP']));+ });++ it('rejects duplicate qualified response entries', () => {+ expect(() =>+ buildCustomToolsMapFromResponse(+ [],+ [alpha, beta],+ response({+ custom_tools: [],+ custom_toolkits: [+ {+ slug: 'ALPHA',+ tools: [+ { slug: 'LOCAL_ALPHA_GREP', original_slug: 'GREP' },+ { slug: 'LOCAL_ALPHA_GREP_2', original_slug: 'GREP' },+ ],+ },+ ],+ })+ )+ ).toThrow('already registered for toolkit');+ });+});+// ────────────────────────────────────────────────────────────────// serializeCustomTools()// ────────────────────────────────────────────────────────────────