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.

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.md
new file mode 100644
index 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.mdx
index 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.
```python
def execute(tool_slug: str, arguments: Dict[str, Any | None] = ..., account: str | None = ...) -> SessionExecuteResponse
diff --git a/docs/content/reference/sdk-reference/typescript/session.mdx b/docs/content/reference/sdk-reference/typescript/session.mdx
index 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<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.
```typescript
async 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.py
index 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) -> s
return 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 tools
for 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:
return
handle, 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 None
and (
normalized in custom_tools_map.by_original_slug
+ or normalized in custom_tools_map.ambiguous_original_slugs
or 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.py
index 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 t
from 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 None
upper = 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.py
index 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]] = None
tools: 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.py
index 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 HttpClient
from 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 API
serialized = _serialize_arguments(arguments)
diff --git a/python/composio/core/models/tool_router_session.py b/python/composio/core/models/tool_router_session.py
index 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 HttpClient
from composio.client.types import Tool
from composio.core.models._modifiers import Modifiers, apply_modifier_by_type
from 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 backend
return 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 in
multi-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 = bare
tools.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.py
index 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, Field
from 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.fixture
def 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_slug
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)
+ 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) == 1
assert 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 True
assert 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.ts
index 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.ts
index 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 arguments
diff --git a/ts/packages/core/test/models/customTool.test.ts b/ts/packages/core/test/models/customTool.test.ts
index 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()
// ────────────────────────────────────────────────────────────────