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
feat(python)!: replace factory functions with decorator API for custom tools
Dhawal Upadhyay6196f2e338ff
diff --git a/python/composio/__init__.py b/python/composio/__init__.pyindex 143e25b44..033065579 100644--- a/python/composio/__init__.py+++ b/python/composio/__init__.py@@ -1,8 +1,4 @@from .__version__ import __version__-from .core.models.custom_tool import (- experimental_create_tool,- experimental_create_toolkit,-)from .core.models.custom_tool_types import (CustomTool,CustomToolkit,@@ -47,8 +43,6 @@ __all__ = ("WebhookEventType","after_execute","before_execute",- "experimental_create_tool",- "experimental_create_toolkit","is_connection_expired_event","schema_modifier","__version__",diff --git a/python/composio/core/models/__init__.py b/python/composio/core/models/__init__.pyindex 9770a0612..565b9da62 100644--- a/python/composio/core/models/__init__.py+++ b/python/composio/core/models/__init__.py@@ -1,6 +1,6 @@from .auth_configs import AuthConfigsfrom .connected_accounts import ConnectedAccounts-from .custom_tool import experimental_create_tool, experimental_create_toolkit+from .custom_tool import ExperimentalAPI, ExperimentalToolkitfrom .custom_tool_types import (CustomTool,CustomToolkit,@@ -35,6 +35,8 @@ __all__ = ["ConnectionStatusEnum","CustomTool","CustomToolkit",+ "ExperimentalAPI",+ "ExperimentalToolkit","MCP","ProxyExecuteResponse","RegisteredCustomTool",@@ -51,7 +53,5 @@ __all__ = ["WebhookConnectionMetadata","WebhookEvent","WebhookEventType",- "experimental_create_tool",- "experimental_create_toolkit","is_connection_expired_event",]diff --git a/python/composio/core/models/custom_tool.py b/python/composio/core/models/custom_tool.pyindex 318d89057..a6185b40d 100644--- a/python/composio/core/models/custom_tool.py+++ b/python/composio/core/models/custom_tool.py@@ -1,29 +1,47 @@-"""Factory functions for creating custom tools and toolkits.+"""Custom tools and toolkits for tool router sessions.++Decorator API for defining custom tools that run in-process alongside+remote Composio tools. Accessed via ``composio.experimental``.Usage::- from composio import experimental_create_tool, experimental_create_toolkitfrom pydantic import BaseModel, Field+ from composio import Composio++ composio = Composio()class GrepInput(BaseModel):pattern: str = Field(description="Pattern to search for")- grep = experimental_create_tool("GREP",- name="Grep Search",- description="Search for patterns in files",- input_params=GrepInput,- execute=lambda input, ctx: {"matches": []},- )+ @composio.experimental.tool()+ def grep(input: GrepInput, ctx):+ \"\"\"Search for a pattern in local files.\"\"\"+ return {"matches": []}- dev_tools = experimental_create_toolkit("DEV_TOOLS",+ dev_tools = composio.experimental.Toolkit(+ slug="DEV_TOOLS",name="Dev Tools",description="Local dev utilities",- tools=[grep],+ )++ @dev_tools.tool()+ def search_code(input: GrepInput, ctx):+ \"\"\"Search developer resources.\"\"\"+ return {"results": []}++ session = composio.create(+ user_id="default",+ experimental={+ "custom_tools": [grep],+ "custom_toolkits": [dev_tools],+ },)"""from __future__ import annotations+import asyncio+import inspectimport typing as tfrom pydantic import BaseModel@@ -120,18 +138,17 @@ def _get_input_json_schema(model: t.Type[BaseModel]) -> t.Dict[str, t.Any]:schema["properties"] = full_schema["properties"]if "required" in full_schema:schema["required"] = full_schema["required"]- # Inline $defs if present (Pydantic puts nested models there)if "$defs" in full_schema:schema["$defs"] = full_schema["$defs"]return schema# ────────────────────────────────────────────────────────────────-# Factory functions+# Internal tool creation (used by decorator API)# ────────────────────────────────────────────────────────────────-def experimental_create_tool(+def _create_tool(slug: str,*,name: str,@@ -141,80 +158,22 @@ def experimental_create_tool(extends_toolkit: t.Optional[str] = None,output_params: t.Optional[t.Type[BaseModel]] = None,) -> CustomTool:- """Create a custom tool for use in tool router sessions.-- The returned object is a lightweight reference containing the tool's metadata- and execute function. Pass it to- ``composio.create(user_id, experimental={"custom_tools": [...]})``- to bind it to a session.-- Just return the result data from ``execute``, or raise an error.- The SDK wraps it into the standard response format internally.-- :param slug: Unique tool identifier (alphanumeric, underscores, hyphens;- no LOCAL_ or COMPOSIO_ prefix)- :param name: Human-readable display name- :param description: Tool description (used for BM25 search matching)- :param input_params: Pydantic BaseModel class for input parameters- :param execute: Function ``(input, ctx) -> dict`` that executes the tool- :param extends_toolkit: Composio toolkit slug to inherit auth from (e.g. 'gmail')- :param output_params: Optional Pydantic BaseModel class for output documentation- :returns: A CustomTool to pass to session creation-- Example — standalone tool (no auth)::-- class GrepInput(BaseModel):- pattern: str = Field(description="Pattern to search for")- path: str = Field(description="File path")-- grep = experimental_create_tool("GREP",- name="Grep Search",- description="Search for patterns in files",- input_params=GrepInput,- execute=lambda input, ctx: {"matches": []},- )-- Example — tool extending a Composio toolkit (inherits auth)::-- class DraftInput(BaseModel):- to: str = Field(description="Recipient email")- subject: str = Field(description="Subject")- body: str = Field(description="Body")-- create_draft = experimental_create_tool("CREATE_DRAFT",- name="Create Gmail draft",- description="Create a real Gmail draft via the Gmail API",- extends_toolkit="gmail",- input_params=DraftInput,- execute=lambda input, ctx: ctx.proxy_execute(- toolkit="gmail",- endpoint="https://gmail.googleapis.com/gmail/v1/users/me/drafts",- method="POST",- body={"message": {"raw": "..."}},- ),- )- """- context = "experimental_create_tool"+ """Internal: create and validate a CustomTool."""+ context = "experimental.tool"- # Validate slug_validate_slug(slug, context)- # Validate required fieldsif not name:raise ValidationError(f"{context}: name is required")if not description:raise ValidationError(f"{context}: description is required")- # Validate input_params is a Pydantic BaseModel subclass (not an instance)- # and produces an object-shaped JSON Schema (rejects RootModel[list[...]] etc.)if not isinstance(input_params, type) or not issubclass(input_params, BaseModel):raise ValidationError(f"{context}: input_params must be a Pydantic BaseModel subclass. "f"Tool input parameters are always an object with named properties.")- # Reject RootModel and other non-object schemas — tool router only passes- # named argument objects, so the schema must have named properties.try:from pydantic import RootModel@@ -225,28 +184,22 @@ def experimental_create_tool(f"named properties.")except ImportError:- pass # RootModel not available in older Pydantic+ pass- # Validate execute is callable and synchronousif not callable(execute):raise ValidationError(f"{context}: execute must be a callable")- import asyncio-if asyncio.iscoroutinefunction(execute):raise ValidationError(f"{context}: execute must be a synchronous function, not async. "f"The Composio Python SDK is synchronous — use a regular "- f"'def execute(input, ctx)' instead of 'async def'."+ f"'def fn(input, ctx)' instead of 'async def'.")- # Early length validation_validate_slug_length(slug, extends_toolkit, context)- # Convert Pydantic model → JSON Schemainput_schema = _get_input_json_schema(input_params)- # Convert output schema if providedoutput_schema: t.Optional[t.Dict[str, t.Any]] = Noneif output_params is not None:if not isinstance(output_params, type) or not issubclass(@@ -269,65 +222,248 @@ def experimental_create_tool()-def experimental_create_toolkit(- slug: str,+def _infer_tool_from_function(+ fn: t.Callable[..., t.Any],*,- name: str,- description: str,- tools: t.List[CustomTool],-) -> CustomToolkit:- """Create a custom toolkit that groups related tools.+ slug: t.Optional[str] = None,+ name: t.Optional[str] = None,+ description: t.Optional[str] = None,+ extends_toolkit: t.Optional[str] = None,+ output_params: t.Optional[t.Type[BaseModel]] = None,+) -> CustomTool:+ """Create a CustomTool by inferring metadata from a decorated function.++ - slug: from ``fn.__name__.upper()``+ - name: from ``fn.__name__`` humanized+ - description: from ``fn.__doc__``+ - input_params: from the first parameter with a BaseModel type annotation+ """+ # Infer slug+ actual_slug = slug or fn.__name__.upper()+ actual_name = name or fn.__name__.replace("_", " ").title()+ actual_description = description or (fn.__doc__ or "").strip()++ if not actual_description:+ raise ValidationError(+ f"experimental.tool: description is required. "+ f'Add a docstring to "{fn.__name__}" or pass description=...'+ )++ # Infer input_params from type annotation+ sig = inspect.signature(fn)+ params = list(sig.parameters.values())+ input_params: t.Optional[t.Type[BaseModel]] = None+ for p in params:+ if p.annotation is not inspect.Parameter.empty:+ ann = p.annotation+ if isinstance(ann, type) and issubclass(ann, BaseModel):+ input_params = ann+ break++ if input_params is None:+ raise ValidationError(+ f'experimental.tool: could not infer input parameters for "{fn.__name__}". '+ f"Annotate a parameter with a Pydantic BaseModel subclass, e.g. "+ f"def {fn.__name__}(input: MyInput, ctx): ..."+ )++ # Wrap function to match CustomToolExecuteFn: (input, ctx) -> dict+ # Support both (input) and (input, ctx) signatures+ num_params = len(params)+ if num_params <= 1:++ def execute(input: t.Any, ctx: t.Any) -> t.Dict[str, t.Any]:+ return fn(input)+ else:+ execute = fn++ return _create_tool(+ slug=actual_slug,+ name=actual_name,+ description=actual_description,+ input_params=input_params,+ execute=execute,+ extends_toolkit=extends_toolkit,+ output_params=output_params,+ )- Tools passed here must NOT have ``extends_toolkit`` set — they inherit the- toolkit identity instead.- :param slug: Unique toolkit identifier (alphanumeric, underscores, hyphens;- no LOCAL_ or COMPOSIO_ prefix)- :param name: Human-readable display name- :param description: Toolkit description- :param tools: List of CustomTool objects to include in this toolkit- :returns: A CustomToolkit to pass to session creation+# ────────────────────────────────────────────────────────────────+# ExperimentalToolkit — custom toolkit with .tool() decorator+# ────────────────────────────────────────────────────────────────+++class ExperimentalToolkit:+ """Custom toolkit that groups related tools under one namespace.++ Use ``@toolkit.tool()`` to add tools. Pass the toolkit to+ ``composio.create(experimental={"custom_toolkits": [toolkit]})``.++ Tools added to a toolkit must NOT use ``extends_toolkit`` — they+ inherit the toolkit identity instead.Example::- dev_tools = experimental_create_toolkit("DEV_TOOLS",+ dev_tools = composio.experimental.Toolkit(+ slug="DEV_TOOLS",name="Dev Tools",description="Local dev utilities",- tools=[grep_tool, sed_tool],)++ @dev_tools.tool()+ def search_code(input: SearchInput, ctx):+ \"\"\"Search developer resources.\"\"\"+ return {"results": []}"""- context = "experimental_create_toolkit"- # Validate slug- _validate_slug(slug, context)+ def __init__(self, *, slug: str, name: str, description: str) -> None:+ context = "experimental.Toolkit"+ _validate_slug(slug, context)+ if not name:+ raise ValidationError(f"{context}: name is required")+ if not description:+ raise ValidationError(f"{context}: description is required")++ self.slug = slug+ self.name = name+ self.description = description+ self._tools: t.List[CustomTool] = []++ @property+ def tools(self) -> t.Tuple[CustomTool, ...]:+ return tuple(self._tools)++ @t.overload+ def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...++ @t.overload+ def tool(+ self,+ *,+ slug: t.Optional[str] = None,+ name: t.Optional[str] = None,+ description: t.Optional[str] = None,+ output_params: t.Optional[t.Type[BaseModel]] = None,+ ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...++ def tool(+ self,+ fn: t.Optional[t.Callable[..., t.Any]] = None,+ *,+ slug: t.Optional[str] = None,+ name: t.Optional[str] = None,+ description: t.Optional[str] = None,+ output_params: t.Optional[t.Type[BaseModel]] = None,+ ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:+ """Decorator to add a tool to this toolkit.++ Infers slug, name, description, and input_params from the function+ if not explicitly provided.+ """++ def decorator(f: t.Callable[..., t.Any]) -> CustomTool:+ custom_tool = _infer_tool_from_function(+ f,+ slug=slug,+ name=name,+ description=description,+ output_params=output_params,+ # No extends_toolkit for toolkit tools+ )+ if custom_tool.extends_toolkit:+ raise ValidationError(+ f'experimental.Toolkit.tool: tool "{custom_tool.slug}" has '+ f"extends_toolkit set. Tools in a custom toolkit must not "+ f"use extends_toolkit — they inherit the toolkit identity."+ )+ _validate_slug_length(+ custom_tool.slug, self.slug, f'experimental.Toolkit("{self.slug}").tool'+ )+ self._tools.append(custom_tool)+ return custom_tool- # Validate required fields- if not name:- raise ValidationError(f"{context}: name is required")- if not description:- raise ValidationError(f"{context}: description is required")+ if fn is not None:+ return decorator(fn)+ return decorator- # Non-empty tools required- if not tools:- raise ValidationError(f"{context}: at least one tool is required")- # Validate each tool- for tool in tools:- if tool.extends_toolkit:- raise ValidationError(- f'{context}: tool "{tool.slug}" has extends_toolkit set. '- f"Tools in a custom toolkit must not use extends_toolkit — "- f"they inherit the toolkit identity instead."+# ────────────────────────────────────────────────────────────────+# ExperimentalAPI — the composio.experimental namespace+# ────────────────────────────────────────────────────────────────+++class ExperimentalAPI:+ """Experimental APIs accessed via ``composio.experimental``.++ Provides decorators for creating custom tools and toolkits+ that run in-process alongside remote Composio tools.+ """++ Toolkit = ExperimentalToolkit++ @t.overload+ def tool(self, fn: t.Callable[..., t.Any], /) -> CustomTool: ...++ @t.overload+ def tool(+ self,+ *,+ slug: t.Optional[str] = None,+ name: t.Optional[str] = None,+ description: t.Optional[str] = None,+ extends_toolkit: t.Optional[str] = None,+ output_params: t.Optional[t.Type[BaseModel]] = None,+ ) -> t.Callable[[t.Callable[..., t.Any]], CustomTool]: ...++ def tool(+ self,+ fn: t.Optional[t.Callable[..., t.Any]] = None,+ *,+ slug: t.Optional[str] = None,+ name: t.Optional[str] = None,+ description: t.Optional[str] = None,+ extends_toolkit: t.Optional[str] = None,+ output_params: t.Optional[t.Type[BaseModel]] = None,+ ) -> t.Union[CustomTool, t.Callable[[t.Callable[..., t.Any]], CustomTool]]:+ """Decorator to create a custom tool from a function.++ Infers slug, name, description, and input_params from the function.+ Override any with explicit keyword arguments.++ Examples::++ # Bare decorator — no parens+ @composio.experimental.tool+ def grep(input: GrepInput, ctx):+ \"\"\"Search for a pattern.\"\"\"+ return {"matches": []}++ # With parens — no args+ @composio.experimental.tool()+ def grep(input: GrepInput, ctx):+ \"\"\"Search for a pattern.\"\"\"+ return {"matches": []}++ # With extends_toolkit — inherits auth+ @composio.experimental.tool(extends_toolkit="gmail")+ def create_draft(input: DraftInput, ctx):+ \"\"\"Create a Gmail draft.\"\"\"+ return ctx.proxy_execute(toolkit="gmail", ...)+ """++ def decorator(f: t.Callable[..., t.Any]) -> CustomTool:+ return _infer_tool_from_function(+ f,+ slug=slug,+ name=name,+ description=description,+ extends_toolkit=extends_toolkit,+ output_params=output_params,)- # Early length validation with toolkit slug- _validate_slug_length(tool.slug, slug, f'{context}("{slug}")')- return CustomToolkit(- slug=slug,- name=name,- description=description,- tools=tuple(tools),- )+ if fn is not None:+ return decorator(fn)+ return decorator# ────────────────────────────────────────────────────────────────@@ -354,7 +490,7 @@ def serialize_custom_tools(tools: t.List[CustomTool]) -> t.List[t.Dict[str, t.Andef serialize_custom_toolkits(- toolkits: t.List[CustomToolkit],+ toolkits: t.Sequence[t.Union[CustomToolkit, ExperimentalToolkit]],) -> t.List[t.Dict[str, t.Any]]:"""Serialize custom toolkits into the format expected by the backend."""result = []@@ -388,12 +524,9 @@ def serialize_custom_toolkits(def build_custom_tools_map(tools: t.List[CustomTool],- toolkits: t.Optional[t.List[CustomToolkit]] = None,+ toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]] = None,) -> CustomToolsMap:- """Build a CustomToolsMap from custom tools and toolkits.-- Used internally by ToolRouter.create() to construct the per-session routing map.- """+ """Build a CustomToolsMap from custom tools and toolkits."""by_final_slug: t.Dict[str, CustomToolsMapEntry] = {}by_original_slug: t.Dict[str, CustomToolsMapEntry] = {}@@ -445,24 +578,20 @@ def build_custom_tools_map(return CustomToolsMap(by_final_slug=by_final_slug,by_original_slug=by_original_slug,- toolkits=list(toolkits) if toolkits else None,+ toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type])def build_custom_tools_map_from_response(tools: t.List[CustomTool],- toolkits: t.Optional[t.List[CustomToolkit]],+ toolkits: t.Optional[t.List[t.Union[CustomToolkit, ExperimentalToolkit]]],experimental: t.Optional[SessionCreateResponseExperimental],) -> CustomToolsMap:- """Build a CustomToolsMap using the slug/original_slug mapping from the backend response.-- Uses the backend's authoritative prefixed slugs instead of computing them client-side.- """+ """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] = {}- # Build lookup from original slug → handle + toolkit- # Detect duplicate original slugs across standalone tools and toolkit tools+ # Build lookup from original slug -> handle + toolkithandles_by_original: t.Dict[str, t.Tuple[CustomTool, t.Optional[str]]] = {}for handle in tools:key = handle.slug.upper()@@ -488,22 +617,19 @@ def build_custom_tools_map_from_response() -> None:match = handles_by_original.get(original_slug.upper())if not match:- return # Response tool not found in our handles+ returnhandle, default_toolkit = matchresolved_toolkit = toolkit if toolkit is not None else default_toolkitentry = CustomToolsMapEntry(handle=handle, final_slug=final_slug, toolkit=resolved_toolkit)- # Store with uppercased keys to match find_custom_tool's .upper() lookupby_final_slug[final_slug.upper()] = entryby_original_slug[original_slug.upper()] = entry- # Map standalone custom tools from responseif experimental and experimental.custom_tools:for ct in experimental.custom_tools:add_entry(ct.slug, ct.original_slug, ct.extends_toolkit)- # Map toolkit custom tools from responseif experimental and experimental.custom_toolkits:for ctk in experimental.custom_toolkits:for ctk_tool in ctk.tools:@@ -512,5 +638,5 @@ def build_custom_tools_map_from_response(return CustomToolsMap(by_final_slug=by_final_slug,by_original_slug=by_original_slug,- toolkits=list(toolkits) if toolkits else None,+ toolkits=list(toolkits) if toolkits else None, # type: ignore[arg-type])diff --git a/python/composio/core/models/tool_router.py b/python/composio/core/models/tool_router.pyindex 5409ddd5f..8cefafd6b 100644--- a/python/composio/core/models/tool_router.py+++ b/python/composio/core/models/tool_router.py@@ -18,6 +18,7 @@ from composio_client.types.tool_router import session_create_paramsfrom composio.client import HttpClientfrom composio.core.models.base import Resourcefrom composio.core.models.custom_tool import (+ ExperimentalToolkit,build_custom_tools_map_from_response,serialize_custom_tools,serialize_custom_toolkits,@@ -194,7 +195,7 @@ class ToolRouterExperimentalConfig(te.TypedDict, total=False):assistive_prompt: ToolRouterAssistivePromptConfigcustom_tools: t.List["CustomTool"]- custom_toolkits: t.List["CustomToolkit"]+ custom_toolkits: t.List[t.Union["CustomToolkit", "ExperimentalToolkit"]]@dataclassdiff --git a/python/composio/sdk.py b/python/composio/sdk.pyindex 599c9653a..09b69e0e5 100644--- a/python/composio/sdk.py+++ b/python/composio/sdk.py@@ -144,6 +144,11 @@ class Composio(t.Generic[TTool, TToolCollection], WithLogger):self.connected_accounts = ConnectedAccounts(client=self._client)self.mcp = MCP(client=self._client)+ # experimental API — decorators for custom tools and toolkits+ from composio.core.models.custom_tool import ExperimentalAPI++ self.experimental = ExperimentalAPI()+# initialize tool router methodsself.tool_router = ToolRouter(client=self._client,diff --git a/python/tests/test_custom_tools.py b/python/tests/test_custom_tools.pyindex 4387949d9..340f15c03 100644--- a/python/tests/test_custom_tools.py+++ b/python/tests/test_custom_tools.py@@ -1,7 +1,8 @@"""Tests for custom tools in tool router sessions.Covers:-- Factory function validation (slug rules, required fields, Pydantic model check)+- Decorator API (inference, overrides, validation)+- Toolkit builder with @toolkit.tool() decorator- Slug prefixing and collision detection- Serialization to API format- Custom tool execution (validation, defaults, errors)@@ -16,8 +17,9 @@ from unittest.mock import MagicMockimport pytestfrom pydantic import BaseModel, Field-from composio import experimental_create_tool, experimental_create_toolkitfrom composio.core.models.custom_tool import (+ ExperimentalAPI,+ ExperimentalToolkit,build_custom_tools_map,build_custom_tools_map_from_response,serialize_custom_tools,@@ -36,6 +38,8 @@ from composio.exceptions import ValidationError# Fixtures# ────────────────────────────────────────────────────────────────+exp = ExperimentalAPI()+class GrepInput(BaseModel):pattern: str = Field(description="Pattern to search for")@@ -54,50 +58,41 @@ class SetRoleInput(BaseModel):@pytest.fixturedef grep_tool():- return experimental_create_tool(- "GREP",- name="Grep Search",- description="Search for patterns in files",- input_params=GrepInput,- execute=lambda input, ctx: {"matches": [input.pattern], "path": input.path},- )+ @exp.tool()+ def grep(input: GrepInput, ctx):+ """Search for patterns in files."""+ return {"matches": [input.pattern], "path": input.path}++ return grep@pytest.fixturedef email_tool():- return experimental_create_tool(- "GET_EMAILS",- name="Get Emails",- description="Get emails from Gmail",- input_params=EmailInput,- execute=lambda input, ctx: {"emails": []},- extends_toolkit="gmail",- )+ @exp.tool(extends_toolkit="gmail")+ def get_emails(input: EmailInput, ctx):+ """Get emails from Gmail."""+ return {"emails": []}++ return get_emails@pytest.fixturedef set_role_tool():- return experimental_create_tool(- "SET_ROLE",- name="Set role",- description="Set a user's role",- input_params=SetRoleInput,- execute=lambda input, ctx: {- "user_id": input.user_id,- "role": input.role,- "updated": True,- },- )+ @exp.tool()+ def set_role(input: SetRoleInput, ctx):+ """Set a user's role."""+ return {"user_id": input.user_id, "role": input.role, "updated": True}++ return set_role@pytest.fixturedef role_toolkit(set_role_tool):- return experimental_create_toolkit(- "ROLE_MANAGER",- name="Role Manager",- description="Manage user roles",- tools=[set_role_tool],+ tk = ExperimentalToolkit(+ slug="ROLE_MANAGER", name="Role Manager", description="Manage user roles")+ tk._tools.append(set_role_tool)+ return tkclass MockSessionContext:@@ -111,248 +106,179 @@ class MockSessionContext:# ────────────────────────────────────────────────────────────────-# Factory validation tests+# Decorator API tests# ────────────────────────────────────────────────────────────────-class TestCreateCustomTool:- def test_creates_tool_with_valid_params(self, grep_tool):- assert grep_tool.slug == "GREP"- assert grep_tool.name == "Grep Search"- assert grep_tool.description == "Search for patterns in files"- assert grep_tool.extends_toolkit is None- assert grep_tool.input_schema["type"] == "object"- assert "pattern" in grep_tool.input_schema["properties"]- assert grep_tool.output_schema is None-- def test_creates_extension_tool(self, email_tool):- assert email_tool.slug == "GET_EMAILS"- assert email_tool.extends_toolkit == "gmail"-- def test_slug_empty(self):- with pytest.raises(ValidationError, match="slug is required"):- experimental_create_tool(- "",- name="Bad",- description="Bad",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_slug_invalid_chars(self):- with pytest.raises(ValidationError, match="alphanumeric"):- experimental_create_tool(- "BAD SLUG!",- name="Bad",- description="Bad",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_slug_local_prefix(self):- with pytest.raises(ValidationError, match="LOCAL_"):- experimental_create_tool(- "LOCAL_BAD",- name="Bad",- description="Bad",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_slug_composio_prefix(self):- with pytest.raises(ValidationError, match="COMPOSIO_"):- experimental_create_tool(- "COMPOSIO_BAD",- name="Bad",- description="Bad",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_name_required(self):- with pytest.raises(ValidationError, match="name is required"):- experimental_create_tool(- "GOOD",- name="",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_description_required(self):+class TestDecoratorTool:+ def test_bare_decorator(self):+ @exp.tool+ def my_tool(input: GrepInput, ctx):+ """My tool description."""+ return {}++ assert my_tool.slug == "MY_TOOL"+ assert my_tool.name == "My Tool"+ assert my_tool.description == "My tool description."+ assert my_tool.input_schema["type"] == "object"+ assert "pattern" in my_tool.input_schema["properties"]++ def test_decorator_with_parens(self):+ @exp.tool()+ def search(input: GrepInput, ctx):+ """Search stuff."""+ return {}++ assert search.slug == "SEARCH"++ def test_decorator_with_extends_toolkit(self):+ @exp.tool(extends_toolkit="gmail")+ def fetch_mail(input: EmailInput, ctx):+ """Fetch mail."""+ return {}++ assert fetch_mail.extends_toolkit == "gmail"++ def test_decorator_explicit_overrides(self):+ @exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")+ def whatever(input: GrepInput, ctx):+ """Original docstring."""+ return {}++ assert whatever.slug == "CUSTOM"+ assert whatever.name == "Custom Name"+ assert whatever.description == "Custom desc"++ def test_infers_from_function_name(self):+ @exp.tool()+ def search_user_by_email(input: GrepInput, ctx):+ """Find a user."""+ return {}++ assert search_user_by_email.slug == "SEARCH_USER_BY_EMAIL"+ assert search_user_by_email.name == "Search User By Email"++ def test_infers_description_from_docstring(self):+ @exp.tool()+ def my_func(input: GrepInput, ctx):+ """Trimmed docstring."""+ return {}++ assert my_func.description == "Trimmed docstring."++ def test_missing_docstring_raises(self):with pytest.raises(ValidationError, match="description is required"):- experimental_create_tool(- "GOOD",- name="Name",- description="",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_input_params_must_be_basemodel_subclass(self):- with pytest.raises(ValidationError, match="BaseModel subclass"):- experimental_create_tool(- "GOOD",- name="Name",- description="Desc",- input_params=dict, # type: ignore- execute=lambda i, c: {},- )-- def test_input_params_must_not_be_instance(self):++ @exp.tool()+ def no_doc(input: GrepInput, ctx):+ return {}++ def test_missing_basemodel_annotation_raises(self):with pytest.raises(ValidationError, match="BaseModel subclass"):- experimental_create_tool(- "GOOD",- name="Name",- description="Desc",- input_params=GrepInput(pattern="x"), # type: ignore- execute=lambda i, c: {},- )-- def test_execute_must_be_callable(self):- with pytest.raises(ValidationError, match="callable"):- experimental_create_tool(- "GOOD",- name="Name",- description="Desc",- input_params=GrepInput,- execute="not a function", # type: ignore- )-- def test_slug_length_validation_standalone(self):- # LOCAL_ + 55 chars = 61 > 60- with pytest.raises(ValidationError, match="too long"):- experimental_create_tool(- "A" * 55,- name="Name",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- )-- def test_slug_length_validation_extension(self):- # LOCAL_ + GMAIL_ + slug must be <= 60- with pytest.raises(ValidationError, match="too long"):- experimental_create_tool(- "A" * 50,- name="Name",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- extends_toolkit="gmail",- )-- def test_output_params(self):- class OutputSchema(BaseModel):- matches: int-- tool = experimental_create_tool(- "TOOL",- name="Tool",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- output_params=OutputSchema,- )- assert tool.output_schema is not None- assert "properties" in tool.output_schema- def test_rejects_root_model(self):+ @exp.tool()+ def bad(x: str, ctx):+ """Bad tool."""+ return {}++ def test_async_function_rejected(self):+ with pytest.raises(ValidationError, match="synchronous"):++ @exp.tool()+ async def async_tool(input: GrepInput, ctx):+ """Async tool."""+ return {}++ def test_root_model_rejected(self):from pydantic import RootModelclass ListInput(RootModel[list[int]]):passwith pytest.raises(ValidationError, match="RootModel"):- experimental_create_tool(- "BAD",- name="Bad",- description="Desc",- input_params=ListInput,- execute=lambda i, c: {},- )-- def test_rejects_async_execute(self):- async def async_execute(input, ctx):- return {"result": "ok"}- with pytest.raises(ValidationError, match="synchronous"):- experimental_create_tool(- "ASYNC",- name="Async",- description="Desc",- input_params=GrepInput,- execute=async_execute,- )+ @exp.tool()+ def bad(input: ListInput, ctx):+ """Bad tool."""+ return {}++ def test_single_param_function(self):+ """Function with only input param (no ctx) should work."""++ @exp.tool()+ def simple(input: GrepInput):+ """Simple tool."""+ return {"pattern": input.pattern}++ m = build_custom_tools_map([simple])+ entry = find_custom_tool(m, "SIMPLE")+ result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore+ assert result["successful"] is True+ assert result["data"]["pattern"] == "test"++ def test_slug_validation(self):+ with pytest.raises(ValidationError, match="LOCAL_"):++ @exp.tool(slug="LOCAL_BAD")+ def bad(input: GrepInput, ctx):+ """Bad tool."""+ return {}++ def test_creates_frozen_custom_tool(self):+ @exp.tool()+ def frozen(input: GrepInput, ctx):+ """Frozen tool."""+ return {}++ with pytest.raises(AttributeError):+ frozen.slug = "NEW" # type: ignoredef test_input_schema_includes_defaults(self, grep_tool):- # path has default="." - Pydantic won't include it in requiredassert "pattern" in grep_tool.input_schema.get("required", [])assert "path" not in grep_tool.input_schema.get("required", [])- def test_frozen_dataclass(self, grep_tool):- with pytest.raises(AttributeError):- grep_tool.slug = "NEW" # type: ignore---class TestCreateCustomToolkit:- def test_creates_toolkit(self, role_toolkit, set_role_tool):- assert role_toolkit.slug == "ROLE_MANAGER"- assert role_toolkit.name == "Role Manager"- assert len(role_toolkit.tools) == 1- assert role_toolkit.tools[0].slug == "SET_ROLE"-- def test_rejects_empty_tools(self):- with pytest.raises(ValidationError, match="at least one tool"):- experimental_create_toolkit(- "TK",- name="TK",- description="Desc",- tools=[],- )-- def test_rejects_extends_toolkit_in_tools(self, email_tool):- with pytest.raises(ValidationError, match="extends_toolkit"):- experimental_create_toolkit(- "TK",- name="TK",- description="Desc",- tools=[email_tool],- )-- def test_slug_length_validation(self):- tool = experimental_create_tool(- "A" * 45,- name="Name",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- )- # LOCAL_ + LONG_TOOLKIT_ + AAAA... would exceed 60- with pytest.raises(ValidationError, match="too long"):- experimental_create_toolkit(- "LONG_TOOLKIT",- name="TK",- description="Desc",- tools=[tool],- )- def test_slug_validation(self):+class TestToolkitBuilder:+ def test_toolkit_with_decorator(self):+ tk = ExperimentalToolkit(slug="MY_TK", name="My TK", description="Desc")++ @tk.tool()+ def tool_a(input: GrepInput, ctx):+ """Tool A."""+ return {}++ @tk.tool()+ def tool_b(input: GrepInput, ctx):+ """Tool B."""+ return {}++ assert tk.slug == "MY_TK"+ assert len(tk.tools) == 2+ assert tk.tools[0].slug == "TOOL_A"+ assert tk.tools[1].slug == "TOOL_B"++ def test_toolkit_bare_decorator(self):+ tk = ExperimentalToolkit(slug="TK2", name="TK2", description="Desc")++ @tk.tool+ def tool_c(input: GrepInput, ctx):+ """Tool C."""+ return {}++ assert len(tk.tools) == 1++ def test_toolkit_slug_validation(self):with pytest.raises(ValidationError, match="LOCAL_"):- experimental_create_toolkit(- "LOCAL_BAD",- name="TK",- description="Desc",- tools=[- experimental_create_tool(- "T",- name="T",- description="D",- input_params=GrepInput,- execute=lambda i, c: {},- )- ],- )+ ExperimentalToolkit(slug="LOCAL_BAD", name="Bad", description="Desc")++ def test_toolkit_name_required(self):+ with pytest.raises(ValidationError, match="name is required"):+ ExperimentalToolkit(slug="TK", name="", description="Desc")++ def test_toolkit_via_experimental_api(self):+ tk = exp.Toolkit(slug="API_TK", name="API TK", description="Via API")+ assert isinstance(tk, ExperimentalToolkit)+ assert tk.slug == "API_TK"# ────────────────────────────────────────────────────────────────@@ -365,7 +291,6 @@ class TestSerialization:result = serialize_custom_tools([grep_tool])assert len(result) == 1assert result[0]["slug"] == "GREP"- assert result[0]["name"] == "Grep Search"assert result[0]["input_schema"]["type"] == "object"assert "extends_toolkit" not in result[0]@@ -378,7 +303,6 @@ class TestSerialization:assert len(result) == 1assert result[0]["slug"] == "ROLE_MANAGER"assert len(result[0]["tools"]) == 1- assert result[0]["tools"][0]["slug"] == "SET_ROLE"# ────────────────────────────────────────────────────────────────@@ -390,73 +314,28 @@ class TestCustomToolsMap:def test_build_map_standalone(self, grep_tool):m = build_custom_tools_map([grep_tool])assert "LOCAL_GREP" in m.by_final_slug- assert "GREP" in m.by_original_slugdef test_build_map_extension(self, email_tool):m = build_custom_tools_map([email_tool])assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug- assert "GET_EMAILS" in m.by_original_slug- def test_build_map_toolkit(self, set_role_tool, role_toolkit):+ def test_build_map_toolkit(self, role_toolkit):m = build_custom_tools_map([], [role_toolkit])assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug- assert "SET_ROLE" in m.by_original_slug-- def test_build_map_mixed(self, grep_tool, email_tool, role_toolkit):- m = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])- assert len(m.by_final_slug) == 3- assert len(m.by_original_slug) == 3- def test_collision_detection_final_slug(self, grep_tool):+ def test_collision_detection(self, grep_tool):with pytest.raises(ValidationError, match="collision"):build_custom_tools_map([grep_tool, grep_tool])- def test_collision_detection_original_slug(self):- tool1 = experimental_create_tool(- "FOO",- name="Foo",- description="Desc",- input_params=GrepInput,- execute=lambda i, c: {},- )- # Same slug in a toolkit produces different final slug but same original- # This would collide on original slug- toolkit = experimental_create_toolkit(- "TK",- name="TK",- description="D",- tools=[- experimental_create_tool(- "FOO",- name="Foo2",- description="Desc2",- input_params=GrepInput,- execute=lambda i, c: {},- )- ],- )- with pytest.raises(ValidationError, match="collision"):- build_custom_tools_map([tool1], [toolkit])-class TestFindCustomTool:def test_find_by_final_slug(self, grep_tool):m = build_custom_tools_map([grep_tool])- entry = find_custom_tool(m, "LOCAL_GREP")- assert entry is not None- assert entry.final_slug == "LOCAL_GREP"-- def test_find_by_original_slug(self, grep_tool):- m = build_custom_tools_map([grep_tool])- entry = find_custom_tool(m, "GREP")- assert entry is not None- assert entry.final_slug == "LOCAL_GREP"+ assert find_custom_tool(m, "LOCAL_GREP") is not Nonedef test_find_case_insensitive(self, grep_tool):m = build_custom_tools_map([grep_tool])- entry = find_custom_tool(m, "grep")- assert entry is not None- assert entry.final_slug == "LOCAL_GREP"+ assert find_custom_tool(m, "grep") is not Nonedef test_find_nonexistent(self, grep_tool):m = build_custom_tools_map([grep_tool])@@ -468,43 +347,32 @@ class TestFindCustomTool:class TestBuildMapFromResponse:def test_builds_from_response(self, grep_tool, email_tool, role_toolkit):- # Mock response experimentalmock_exp = MagicMock()-- mock_ct1 = MagicMock()- mock_ct1.slug = "LOCAL_GREP"- mock_ct1.original_slug = "GREP"- mock_ct1.extends_toolkit = None-- mock_ct2 = MagicMock()- mock_ct2.slug = "LOCAL_GMAIL_GET_EMAILS"- mock_ct2.original_slug = "GET_EMAILS"- mock_ct2.extends_toolkit = "gmail"-+ mock_ct1 = MagicMock(+ slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None+ )+ mock_ct2 = MagicMock(+ slug="LOCAL_GMAIL_GET_EMAILS",+ original_slug="GET_EMAILS",+ extends_toolkit="gmail",+ )mock_exp.custom_tools = [mock_ct1, mock_ct2]-- mock_ctk = MagicMock()- mock_ctk.slug = "ROLE_MANAGER"- mock_ctk_tool = MagicMock()- mock_ctk_tool.slug = "LOCAL_ROLE_MANAGER_SET_ROLE"- mock_ctk_tool.original_slug = "SET_ROLE"- mock_ctk.tools = [mock_ctk_tool]+ mock_ctk = MagicMock(slug="ROLE_MANAGER")+ mock_ctk.tools = [+ MagicMock(slug="LOCAL_ROLE_MANAGER_SET_ROLE", original_slug="SET_ROLE")+ ]mock_exp.custom_toolkits = [mock_ctk]m = build_custom_tools_map_from_response(- [grep_tool, email_tool],- [role_toolkit],- mock_exp,+ [grep_tool, email_tool], [role_toolkit], mock_exp)-assert "LOCAL_GREP" in m.by_final_slugassert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slugassert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug- assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"# ────────────────────────────────────────────────────────────────-# Custom tool execution tests+# Execution tests# ────────────────────────────────────────────────────────────────@@ -515,52 +383,24 @@ class TestExecuteCustomTool:result = execute_custom_tool(entry, {"pattern": "hello"}, MockSessionContext()) # type: ignoreassert result["successful"] is Trueassert result["data"]["matches"] == ["hello"]- assert result["data"]["path"] == "." # default value- assert result["error"] is None-- def test_applies_pydantic_defaults(self, grep_tool):- m = build_custom_tools_map([grep_tool])- entry = find_custom_tool(m, "GREP")- result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore- assert result["data"]["path"] == "." # default applieddef test_validation_failure(self, grep_tool):m = build_custom_tools_map([grep_tool])entry = find_custom_tool(m, "GREP")- result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore # missing required "pattern"+ result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignoreassert result["successful"] is False- assert "validation" in result["error"].lower()-- def test_execute_function_error(self):- def bad_execute(input, ctx):- raise RuntimeError("Something went wrong")-- tool = experimental_create_tool(- "BAD",- name="Bad",- description="Desc",- input_params=GrepInput,- execute=bad_execute,- )- m = build_custom_tools_map([tool])++ def test_execute_error(self):+ @exp.tool()+ def bad(input: GrepInput, ctx):+ """Bad."""+ raise RuntimeError("boom")++ m = build_custom_tools_map([bad])entry = find_custom_tool(m, "BAD")result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignoreassert result["successful"] is False- assert "Something went wrong" in result["error"]-- def test_execute_returns_none(self):- tool = experimental_create_tool(- "NOOP",- name="Noop",- description="Returns None",- input_params=GrepInput,- execute=lambda i, c: None, # type: ignore- )- m = build_custom_tools_map([tool])- entry = find_custom_tool(m, "NOOP")- result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore- assert result["successful"] is True- assert result["data"] == {}+ assert "boom" in result["error"]# ────────────────────────────────────────────────────────────────@@ -569,447 +409,195 @@ class TestExecuteCustomTool:class TestSessionContextImpl:- def test_user_id(self):- ctx = SessionContextImpl(- client=MagicMock(),- user_id="user-1",- session_id="sess-1",- )- assert ctx.user_id == "user-1"-- def test_execute_routes_to_sibling(self, grep_tool):+ def test_sibling_routing(self, grep_tool):m = build_custom_tools_map([grep_tool])ctx = SessionContextImpl(- client=MagicMock(),- user_id="user-1",- session_id="sess-1",- custom_tools_map=m,+ client=MagicMock(), user_id="u", session_id="s", custom_tools_map=m)result = ctx.execute("GREP", {"pattern": "test"})assert result["successful"] is True- assert result["data"]["matches"] == ["test"]- def test_execute_falls_back_to_remote(self, grep_tool):+ def test_remote_fallback(self, grep_tool):m = build_custom_tools_map([grep_tool])mock_client = MagicMock()- mock_response = MagicMock()- mock_response.data = {"remote": True}- mock_response.error = None- mock_client.tool_router.session.execute.return_value = mock_response-+ mock_client.tool_router.session.execute.return_value = MagicMock(+ data={"remote": True}, error=None+ )ctx = SessionContextImpl(- client=mock_client,- user_id="user-1",- session_id="sess-1",- custom_tools_map=m,+ client=mock_client, user_id="u", session_id="s", custom_tools_map=m)- result = ctx.execute("NONEXISTENT_TOOL", {"arg": "val"})+ ctx.execute("NONEXISTENT", {"arg": "val"})mock_client.tool_router.session.execute.assert_called_once()- assert result["data"] == {"remote": True}def test_proxy_execute(self):mock_client = MagicMock()- mock_response = MagicMock()- mock_response.status = 200- mock_response.data = {"result": "ok"}- mock_response.headers = {"Content-Type": "application/json"}- mock_response.binary_data = None- mock_client.tool_router.session.proxy_execute.return_value = mock_response-- ctx = SessionContextImpl(- client=mock_client,- user_id="user-1",- session_id="sess-1",+ mock_client.tool_router.session.proxy_execute.return_value = MagicMock(+ status=200, data={"ok": True}, headers={}, binary_data=None)+ ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")result = ctx.proxy_execute(- toolkit="gmail",- endpoint="https://gmail.googleapis.com/test",- method="GET",+ toolkit="gmail", endpoint="https://example.com", method="GET")assert result["status"] == 200- assert result["data"] == {"result": "ok"}- mock_client.tool_router.session.proxy_execute.assert_called_once()# ────────────────────────────────────────────────────────────────-# ToolRouterSession integration tests+# ToolRouterSession integration# ────────────────────────────────────────────────────────────────@pytest.fixturedef mock_session_deps(grep_tool, email_tool, role_toolkit):- """Create mock dependencies for ToolRouterSession with custom tools."""- client = MagicMock()- provider = MagicMock()- experimental = MagicMock()- experimental.files = MagicMock()- experimental.assistive_prompt = None-- # Build tools map- tools_map = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])-return {- "client": client,- "provider": provider,- "experimental": experimental,- "tools_map": tools_map,+ "client": MagicMock(),+ "provider": MagicMock(),+ "experimental": MagicMock(),+ "tools_map": build_custom_tools_map([grep_tool, email_tool], [role_toolkit]),}+def _session(deps, **overrides):+ kwargs = dict(+ client=deps["client"],+ provider=deps["provider"],+ auto_upload_download_files=True,+ session_id="s",+ mcp=MagicMock(),+ experimental=deps["experimental"],+ custom_tools_map=deps["tools_map"],+ user_id="u",+ )+ kwargs.update(overrides)+ return ToolRouterSession(**kwargs)++class TestToolRouterSessionCustomTools:- def test_execute_routes_to_local(self, mock_session_deps, grep_tool):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- result = session.execute("GREP", arguments={"pattern": "test"})- # session.execute returns SessionExecuteResponse shape: data, error, log_id- assert result["data"]["matches"] == ["test"]+ def test_execute_local(self, mock_session_deps):+ s = _session(mock_session_deps)+ result = s.execute("GREP", arguments={"pattern": "x"})assert result["error"] is Noneassert result["log_id"] == ""- # Should NOT have called the backendmock_session_deps["client"].tool_router.session.execute.assert_not_called()- def test_execute_routes_to_local_by_final_slug(self, mock_session_deps):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- result = session.execute("LOCAL_GREP", arguments={"pattern": "test"})- assert result["error"] is None-- def test_execute_case_insensitive(self, mock_session_deps):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- result = session.execute("grep", arguments={"pattern": "test"})- assert result["error"] is None-- def test_execute_routes_to_remote(self, mock_session_deps):- mock_response = MagicMock()+ def test_execute_remote(self, mock_session_deps):mock_session_deps["client"- ].tool_router.session.execute.return_value = mock_response-- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- session.execute("GMAIL_SEND_EMAIL", arguments={"to": "[email protected]"})+ ].tool_router.session.execute.return_value = MagicMock()+ s = _session(mock_session_deps)+ s.execute("GMAIL_SEND_EMAIL", arguments={"to": "[email protected]"})mock_session_deps["client"].tool_router.session.execute.assert_called_once()def test_custom_tools_list(self, mock_session_deps):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- tools = session.custom_tools()- assert len(tools) == 3- slugs = {t.slug for t in tools}- assert "LOCAL_GREP" in slugs- assert "LOCAL_GMAIL_GET_EMAILS" in slugs- assert "LOCAL_ROLE_MANAGER_SET_ROLE" in slugs-- def test_custom_tools_filter_by_toolkit(self, mock_session_deps):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- gmail_tools = session.custom_tools(toolkit="gmail")- assert len(gmail_tools) == 1- assert gmail_tools[0].slug == "LOCAL_GMAIL_GET_EMAILS"+ s = _session(mock_session_deps)+ assert len(s.custom_tools()) == 3++ def test_custom_tools_filter(self, mock_session_deps):+ s = _session(mock_session_deps)+ assert len(s.custom_tools(toolkit="gmail")) == 1def test_custom_toolkits_list(self, mock_session_deps):- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- custom_tools_map=mock_session_deps["tools_map"],- user_id="user-1",- )- toolkits = session.custom_toolkits()- assert len(toolkits) == 1- assert toolkits[0].slug == "ROLE_MANAGER"- assert len(toolkits[0].tools) == 1- assert toolkits[0].tools[0].slug == "LOCAL_ROLE_MANAGER_SET_ROLE"-- def test_custom_tools_empty_when_no_map(self):- session = ToolRouterSession(+ s = _session(mock_session_deps)+ tks = s.custom_toolkits()+ assert len(tks) == 1+ assert tks[0].slug == "ROLE_MANAGER"++ def test_empty_when_no_map(self):+ s = ToolRouterSession(client=MagicMock(),provider=MagicMock(),auto_upload_download_files=True,- session_id="sess-1",+ session_id="s",mcp=MagicMock(),experimental=MagicMock(),)- assert session.custom_tools() == []- assert session.custom_toolkits() == []-- def test_proxy_execute(self, mock_session_deps):- mock_response = MagicMock()- mock_response.status = 200- mock_response.data = {"result": "ok"}- mock_response.headers = {"Content-Type": "application/json"}- mock_response.binary_data = None- mock_session_deps[- "client"- ].tool_router.session.proxy_execute.return_value = mock_response-- session = ToolRouterSession(- client=mock_session_deps["client"],- provider=mock_session_deps["provider"],- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=mock_session_deps["experimental"],- )- result = session.proxy_execute(- toolkit="gmail",- endpoint="https://gmail.googleapis.com/test",- method="GET",- )- assert result["status"] == 200- mock_session_deps[- "client"- ].tool_router.session.proxy_execute.assert_called_once()+ assert s.custom_tools() == []# ────────────────────────────────────────────────────────────────-# Multi-execute routing tests+# Multi-execute routing# ────────────────────────────────────────────────────────────────class TestMultiExecuteRouting:- def _make_session(self, grep_tool, mock_client=None):- m = build_custom_tools_map([grep_tool])- client = mock_client or MagicMock()- session = ToolRouterSession(- client=client,+ def _make_session(self, *tools):+ m = build_custom_tools_map(list(tools))+ return ToolRouterSession(+ client=MagicMock(),provider=MagicMock(),auto_upload_download_files=True,- session_id="sess-1",+ session_id="s",mcp=MagicMock(),experimental=MagicMock(),custom_tools_map=m,- user_id="user-1",+ user_id="u",)- return session-- def test_route_all_local(self, grep_tool):- session = self._make_session(grep_tool)- mock_tools_model = MagicMock()- result = session._route_multi_execute(- {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "test"}}]},- mock_tools_model,+ def test_single_local(self, grep_tool):+ s = self._make_session(grep_tool)+ result = s._route_multi_execute(+ {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "x"}}]},+ MagicMock(),None,)- # Single local tool returns unwrappedassert result["successful"] is True- assert result["data"]["matches"] == ["test"]-- def test_route_all_remote(self, grep_tool):- session = self._make_session(grep_tool)- mock_tools_model = MagicMock()-- remote_response = {+ assert result["data"]["matches"] == ["x"]++ def test_all_remote(self, grep_tool):+ s = self._make_session(grep_tool)+ tm = MagicMock()+ remote = {"data": {"results": []}, "error": None, "successful": True}+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote+ result = s._route_multi_execute(+ {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm, None+ )+ assert result == remote++ def test_mixed(self, grep_tool):+ s = self._make_session(grep_tool)+ tm = MagicMock()+ remote = {"data": {"results": [- {"tool_slug": "GMAIL_SEND", "response": {"successful": True}}+ {"tool_slug": "R", "response": {"successful": True, "data": {}}}]},"error": None,"successful": True,}- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (- lambda slug, args: remote_response- )-- result = session._route_multi_execute(+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote+ result = s._route_multi_execute({"tools": [- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "[email protected]"}}+ {"tool_slug": "GREP", "arguments": {"pattern": "x"}},+ {"tool_slug": "REMOTE", "arguments": {}},]},- mock_tools_model,+ tm,None,)- assert result == remote_response+ assert len(result["data"]["results"]) == 2- def test_route_mixed_local_and_remote(self, grep_tool):- session = self._make_session(grep_tool)- mock_tools_model = MagicMock()+ def test_failure_propagated(self):+ @exp.tool()+ def ok_tool(input: GrepInput, ctx):+ """OK."""+ return {"ok": True}- remote_response = {- "data": {- "results": [- {- "tool_slug": "GMAIL_SEND",- "response": {"successful": True, "data": {"sent": True}},- }- ]- },- "error": None,- "successful": True,- }- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (- lambda slug, args: remote_response- )+ @exp.tool()+ def bad_tool(input: GrepInput, ctx):+ """Bad."""+ raise RuntimeError("boom")- result = session._route_multi_execute(- {- "tools": [- {"tool_slug": "GREP", "arguments": {"pattern": "test"}},- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "[email protected]"}},- ]- },- mock_tools_model,- None,- )- # Should have merged results- assert result["successful"] is True- results = result["data"]["results"]- assert len(results) == 2- # First should be the local GREP result- assert results[0]["tool_slug"] == "GREP"- assert results[0]["response"]["successful"] is True- # Second should be the remote result- assert results[1]["tool_slug"] == "GMAIL_SEND"-- def test_route_empty_tools(self, grep_tool):- session = self._make_session(grep_tool)- mock_tools_model = MagicMock()- fallback_result = {"data": {}, "error": None, "successful": True}- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (- lambda slug, args: fallback_result- )-- result = session._route_multi_execute({"tools": []}, mock_tools_model, None)- # Should fall back to remote- assert result == fallback_result-- def test_route_multiple_local_tools(self):- tool1 = experimental_create_tool(- "TOOL_A",- name="A",- description="D",- input_params=GrepInput,- execute=lambda i, c: {"tool": "A", "pattern": i.pattern},- )- tool2 = experimental_create_tool(- "TOOL_B",- name="B",- description="D",- input_params=GrepInput,- execute=lambda i, c: {"tool": "B", "pattern": i.pattern},- )- m = build_custom_tools_map([tool1, tool2])- session = ToolRouterSession(- client=MagicMock(),- provider=MagicMock(),- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=MagicMock(),- custom_tools_map=m,- user_id="user-1",- )- result = session._route_multi_execute(- {- "tools": [- {"tool_slug": "TOOL_A", "arguments": {"pattern": "x"}},- {"tool_slug": "TOOL_B", "arguments": {"pattern": "y"}},- ]- },- MagicMock(),- None,- )- assert result["successful"] is True- results = result["data"]["results"]- assert len(results) == 2- assert results[0]["response"]["data"]["tool"] == "A"- assert results[1]["response"]["data"]["tool"] == "B"-- def test_route_propagates_local_failure(self):- ok_tool = experimental_create_tool(- "OK",- name="OK",- description="D",- input_params=GrepInput,- execute=lambda i, c: {"ok": True},- )- bad_tool = experimental_create_tool(- "BAD",- name="Bad",- description="D",- input_params=GrepInput,- execute=lambda i, c: (_ for _ in ()).throw(RuntimeError("boom")),- )- m = build_custom_tools_map([ok_tool, bad_tool])- session = ToolRouterSession(- client=MagicMock(),- provider=MagicMock(),- auto_upload_download_files=True,- session_id="sess-1",- mcp=MagicMock(),- experimental=MagicMock(),- custom_tools_map=m,- user_id="user-1",- )- result = session._route_multi_execute(+ s = self._make_session(ok_tool, bad_tool)+ result = s._route_multi_execute({"tools": [- {"tool_slug": "OK", "arguments": {"pattern": "x"}},- {"tool_slug": "BAD", "arguments": {"pattern": "y"}},+ {"tool_slug": "OK_TOOL", "arguments": {"pattern": "x"}},+ {"tool_slug": "BAD_TOOL", "arguments": {"pattern": "y"}},]},MagicMock(),None,)- # Overall result should report failureassert result["successful"] is Falseassert "1 out of 2" in result["error"]- # Individual results preserved- results = result["data"]["results"]- assert results[0]["response"]["successful"] is True- assert results[1]["response"]["successful"] is False