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

next
py 1,767 lines 63.7 KB
Raw
1 """Tests for custom tools in tool router sessions.
2
3 Covers:
4 - Decorator API (inference, overrides, validation)
5 - Toolkit builder with @toolkit.tool() decorator
6 - Slug prefixing and collision detection
7 - Serialization to API format
8 - Custom tool execution (validation, defaults, errors)
9 - Routing map building and lookup
10 - SessionContextImpl sibling routing
11 - ToolRouterSession integration (execute routing, local_tools(), local_toolkits())
12 - Multi-execute routing (all-local, all-remote, mixed, parallel)
13 """
14
15 import sys
16 import warnings
17 from dataclasses import replace
18 from unittest.mock import MagicMock
19
20 import pytest
21 from composio_client import omit
22 from composio_client.types.tool_router.session_execute_response import (
23 SessionExecuteResponse,
24 )
25 from composio_client.types.tool_router.session_proxy_execute_response import (
26 BinaryData,
27 SessionProxyExecuteResponse,
28 )
29 from pydantic import BaseModel, Field
30
31 from composio.core.models.custom_tool import (
32 ExperimentalToolkit,
33 assert_no_custom_tool_slugs_in_preload,
34 build_custom_tools_map,
35 build_custom_tools_map_from_response,
36 serialize_custom_toolkits,
37 serialize_custom_tools,
38 )
39 from composio.core.models.custom_tool_execution import (
40 assert_unambiguous_custom_tool_slug,
41 execute_custom_tool,
42 find_custom_tool,
43 )
44 from composio.core.models.custom_tool_types import (
45 CustomTool,
46 RegisteredCustomTool,
47 RegisteredCustomToolkit,
48 )
49 from composio.core.models.experimental import ExperimentalAPI
50 from composio.core.models.session_context import SessionContextImpl
51 from composio.core.models.tool_router_session import (
52 ToolRouterSession,
53 ToolRouterSessionExecuteResponse,
54 )
55 from composio.exceptions import ComposioDeprecationWarning, ValidationError
56 from tests.conftest import mock_http_client
57
58 # ────────────────────────────────────────────────────────────────
59 # Fixtures
60 # ────────────────────────────────────────────────────────────────
61
62 exp = ExperimentalAPI()
63
64
65 class GrepInput(BaseModel):
66 pattern: str = Field(description="Pattern to search for")
67 path: str = Field(default=".", description="File path")
68
69
70 class EmailInput(BaseModel):
71 to: str = Field(description="Recipient email")
72 subject: str = Field(description="Subject")
73
74
75 class SetRoleInput(BaseModel):
76 user_id: str = Field(description="User ID")
77 role: str = Field(default="viewer", description="New role")
78
79
80 @pytest.fixture
81 def grep_tool():
82 @exp.tool()
83 def grep(input: GrepInput, ctx):
84 """Search for patterns in files."""
85 return {"matches": [input.pattern], "path": input.path}
86
87 return grep
88
89
90 @pytest.fixture
91 def duplicate_slug_tools():
92 @exp.tool(slug="GREP")
93 def alpha_grep(input: GrepInput, ctx):
94 """Search Alpha."""
95 return {"toolkit": "alpha", "matches": [input.pattern]}
96
97 @exp.tool(slug="GREP")
98 def beta_grep(input: GrepInput, ctx):
99 """Search Beta."""
100 return {"toolkit": "beta", "matches": [input.pattern]}
101
102 return alpha_grep, beta_grep
103
104
105 @pytest.fixture
106 def email_tool():
107 @exp.tool(extends_toolkit="gmail")
108 def get_emails(input: EmailInput, ctx):
109 """Get emails from Gmail."""
110 return {"emails": []}
111
112 return get_emails
113
114
115 @pytest.fixture
116 def set_role_tool():
117 @exp.tool()
118 def set_role(input: SetRoleInput, ctx):
119 """Set a user's role."""
120 return {"user_id": input.user_id, "role": input.role, "updated": True}
121
122 return set_role
123
124
125 @pytest.fixture
126 def role_toolkit(set_role_tool):
127 tk = ExperimentalToolkit(
128 slug="ROLE_MANAGER", name="Role Manager", description="Manage user roles"
129 )
130 tk._tools.append(set_role_tool)
131 return tk
132
133
134 class MockSessionContext:
135 user_id = "test-user"
136
137 def execute(self, tool_slug, arguments):
138 return {"data": {}, "error": None, "successful": True}
139
140 def proxy_execute(self, **kwargs):
141 return {"status": 200, "data": {}, "headers": {}}
142
143
144 # ────────────────────────────────────────────────────────────────
145 # Decorator API tests
146 # ────────────────────────────────────────────────────────────────
147
148
149 class TestDecoratorTool:
150 def test_bare_decorator(self):
151 @exp.tool
152 def my_tool(input: GrepInput, ctx):
153 """My tool description."""
154 return {}
155
156 assert my_tool.slug == "MY_TOOL"
157 assert my_tool.name == "My Tool"
158 assert my_tool.description == "My tool description."
159 assert my_tool.input_schema["type"] == "object"
160 assert "pattern" in my_tool.input_schema["properties"]
161
162 def test_decorator_with_parens(self):
163 @exp.tool()
164 def search(input: GrepInput, ctx):
165 """Search stuff."""
166 return {}
167
168 assert search.slug == "SEARCH"
169
170 def test_decorator_with_extends_toolkit(self):
171 @exp.tool(extends_toolkit="gmail")
172 def fetch_mail(input: EmailInput, ctx):
173 """Fetch mail."""
174 return {}
175
176 assert fetch_mail.extends_toolkit == "gmail"
177
178 def test_decorator_with_preload(self):
179 @exp.tool(preload=True)
180 def fetch_context(input: GrepInput, ctx):
181 """Fetch context."""
182 return {}
183
184 assert fetch_context.preload is True
185
186 def test_decorator_explicit_overrides(self):
187 @exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
188 def whatever(input: GrepInput, ctx):
189 """Original docstring."""
190 return {}
191
192 assert whatever.slug == "CUSTOM"
193 assert whatever.name == "Custom Name"
194 assert whatever.description == "Custom desc"
195
196 def test_infers_from_function_name(self):
197 @exp.tool()
198 def search_user_by_email(input: GrepInput, ctx):
199 """Find a user."""
200 return {}
201
202 assert search_user_by_email.slug == "SEARCH_USER_BY_EMAIL"
203 assert search_user_by_email.name == "Search User By Email"
204
205 def test_infers_description_from_docstring(self):
206 @exp.tool()
207 def my_func(input: GrepInput, ctx):
208 """Trimmed docstring."""
209 return {}
210
211 assert my_func.description == "Trimmed docstring."
212
213 def test_multiline_docstring(self):
214 @exp.tool()
215 def multi(input: GrepInput, ctx):
216 """Search for users by email.
217
218 This tool searches the internal database for users
219 matching the given pattern. Returns a list of matches.
220
221 Supports wildcards.
222 """
223 return {}
224
225 assert multi.description.startswith("Search for users by email.")
226 # inspect.cleandoc strips indentation
227 assert "\n " not in multi.description
228 assert "Supports wildcards." in multi.description
229
230 def test_indented_docstring_cleaned(self):
231 @exp.tool()
232 def indented(input: GrepInput, ctx):
233 """
234 Leading and trailing whitespace removed.
235 Indentation normalized.
236 """
237 return {}
238
239 assert indented.description == (
240 "Leading and trailing whitespace removed.\nIndentation normalized."
241 )
242
243 def test_missing_docstring_raises(self):
244 with pytest.raises(ValidationError, match="description is required"):
245
246 @exp.tool()
247 def no_doc(input: GrepInput, ctx):
248 return {}
249
250 def test_missing_basemodel_annotation_raises(self):
251 with pytest.raises(ValidationError, match="BaseModel subclass"):
252
253 @exp.tool()
254 def bad(x: str, ctx):
255 """Bad tool."""
256 return {}
257
258 def test_no_params_rejected(self):
259 with pytest.raises(ValidationError, match="at least one parameter"):
260
261 @exp.tool()
262 def no_params():
263 """No params."""
264 return {}
265
266 def test_too_many_params_rejected(self):
267 with pytest.raises(ValidationError, match="at most 2"):
268
269 @exp.tool()
270 def three_params(input: GrepInput, ctx, extra):
271 """Three params."""
272 return {}
273
274 def test_first_param_must_be_basemodel(self):
275 with pytest.raises(ValidationError, match="first parameter"):
276
277 @exp.tool()
278 def swapped(ctx, input: GrepInput):
279 """Swapped order — ctx first, input second."""
280 return {}
281
282 def test_future_annotations_are_resolved(self):
283 namespace = {"exp": exp}
284 exec(
285 """
286 from __future__ import annotations
287
288 from pydantic import BaseModel, Field
289
290
291 class FutureInput(BaseModel):
292 pattern: str = Field(description="Pattern to search for")
293
294
295 @exp.tool()
296 def future_tool(input: FutureInput, ctx):
297 '''Resolved from postponed annotations.'''
298 return {}
299 """,
300 namespace,
301 )
302
303 future_tool = namespace["future_tool"]
304 future_input = namespace["FutureInput"]
305
306 assert future_tool.input_params is future_input
307
308 def test_local_string_annotations_are_resolved(self):
309 def build_tool():
310 class LocalInput(BaseModel):
311 pattern: str = Field(description="Pattern to search for")
312
313 @exp.tool
314 def nested_search(input: "LocalInput", ctx):
315 """Resolved from local string annotations."""
316 return {}
317
318 return nested_search, LocalInput
319
320 local_tool, local_input = build_tool()
321 assert local_tool.input_params is local_input
322
323 def test_input_model_defined_after_tool_names_unresolved_annotation(self):
324 # https://github.com/ComposioHQ/composio/issues/5022
325 with pytest.raises(
326 ValidationError,
327 match=(
328 r"could not resolve the annotation 'LaterInput' .*"
329 r"NameError: name 'LaterInput' is not defined.*"
330 r"Define LaterInput before the tool"
331 ),
332 ):
333 exec(
334 """
335 from __future__ import annotations
336
337 from pydantic import BaseModel
338
339
340 @exp.tool()
341 def later_tool(input: LaterInput, ctx):
342 '''Input model defined below the tool.'''
343 return {}
344
345
346 class LaterInput(BaseModel):
347 query: str
348 """,
349 {"exp": exp},
350 )
351
352 def test_input_model_imported_under_type_checking_names_unresolved_annotation(
353 self,
354 ):
355 with pytest.raises(
356 ValidationError,
357 match=r"could not resolve the annotation 'GrepInput' .*TYPE_CHECKING",
358 ):
359 exec(
360 """
361 from __future__ import annotations
362
363 from typing import TYPE_CHECKING
364
365 if TYPE_CHECKING:
366 from tests.test_custom_tools import GrepInput
367
368
369 @exp.tool()
370 def type_checking_tool(input: GrepInput, ctx):
371 '''Input model only imported for type checkers.'''
372 return {}
373 """,
374 {"exp": exp},
375 )
376
377 def test_unresolvable_ctx_and_return_annotations_are_ignored(self):
378 namespace = {"exp": exp}
379 exec(
380 """
381 from __future__ import annotations
382
383 from typing import TYPE_CHECKING
384
385 from pydantic import BaseModel
386
387 if TYPE_CHECKING:
388 from composio.core.models.custom_tool import SessionContext
389
390
391 class TypedInput(BaseModel):
392 query: str
393
394
395 @exp.tool()
396 def typed_ctx_tool(input: TypedInput, ctx: SessionContext) -> ToolResult:
397 '''ctx and return annotations exist only for type checkers.'''
398 return {}
399 """,
400 namespace,
401 )
402
403 assert namespace["typed_ctx_tool"].input_params is namespace["TypedInput"]
404
405 @pytest.mark.skipif(
406 sys.version_info < (3, 14), reason="lazy annotations need Python 3.14"
407 )
408 def test_lazy_input_model_defined_after_tool_names_unresolved_annotation(self):
409 # dont_inherit keeps this module's compiler flags out, so the
410 # annotations stay lazy instead of becoming strings.
411 code = compile(
412 """
413 from pydantic import BaseModel
414
415
416 @exp.tool()
417 def lazy_later_tool(input: LazyLaterInput, ctx):
418 '''Input model defined below the tool.'''
419 return {}
420
421
422 class LazyLaterInput(BaseModel):
423 query: str
424 """,
425 "<lazy_later_tool>",
426 "exec",
427 dont_inherit=True,
428 )
429 with pytest.raises(
430 ValidationError,
431 match=r"could not resolve the annotation 'LazyLaterInput' .*NameError",
432 ):
433 exec(code, {"exp": exp})
434
435 @pytest.mark.skipif(
436 sys.version_info < (3, 14), reason="lazy annotations need Python 3.14"
437 )
438 def test_lazy_unresolvable_ctx_and_return_annotations_are_ignored(self):
439 code = compile(
440 """
441 from typing import TYPE_CHECKING
442
443 from pydantic import BaseModel
444
445 if TYPE_CHECKING:
446 from composio.core.models.custom_tool import SessionContext
447
448
449 class LazyInput(BaseModel):
450 query: str
451
452
453 @exp.tool()
454 def lazy_ctx_tool(input: LazyInput, ctx: SessionContext) -> ToolResult:
455 '''ctx and return annotations exist only for type checkers.'''
456 return {}
457 """,
458 "<lazy_ctx_tool>",
459 "exec",
460 dont_inherit=True,
461 )
462 namespace = {"exp": exp}
463 exec(code, namespace)
464
465 assert namespace["lazy_ctx_tool"].input_params is namespace["LazyInput"]
466
467 def test_async_function_rejected(self):
468 with pytest.raises(ValidationError, match="async"):
469
470 @exp.tool()
471 async def async_tool(input: GrepInput, ctx):
472 """Async tool."""
473 return {}
474
475 def test_async_single_param_rejected(self):
476 """Async must be caught even when wrapper hides it (single-param path)."""
477 with pytest.raises(ValidationError, match="async"):
478
479 @exp.tool()
480 async def async_single(input: GrepInput):
481 """Async single param."""
482 return {}
483
484 def test_root_model_rejected(self):
485 from pydantic import RootModel
486
487 class ListInput(RootModel[list[int]]):
488 pass
489
490 with pytest.raises(ValidationError, match="RootModel"):
491
492 @exp.tool()
493 def bad(input: ListInput, ctx):
494 """Bad tool."""
495 return {}
496
497 def test_single_param_function(self):
498 """Function with only input param (no ctx) should work."""
499
500 @exp.tool()
501 def simple(input: GrepInput):
502 """Simple tool."""
503 return {"pattern": input.pattern}
504
505 m = build_custom_tools_map([simple])
506 entry = find_custom_tool(m, "SIMPLE")
507 result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
508 assert result["successful"] is True
509 assert result["data"]["pattern"] == "test"
510
511 def test_slug_validation(self):
512 with pytest.raises(ValidationError, match="LOCAL_"):
513
514 @exp.tool(slug="LOCAL_BAD")
515 def bad(input: GrepInput, ctx):
516 """Bad tool."""
517 return {}
518
519 def test_creates_frozen_custom_tool(self):
520 @exp.tool()
521 def frozen(input: GrepInput, ctx):
522 """Frozen tool."""
523 return {}
524
525 with pytest.raises(AttributeError):
526 frozen.slug = "NEW" # type: ignore
527
528 def test_input_schema_includes_defaults(self, grep_tool):
529 assert "pattern" in grep_tool.input_schema.get("required", [])
530 assert "path" not in grep_tool.input_schema.get("required", [])
531
532
533 class TestToolkitBuilder:
534 def test_toolkit_with_decorator(self):
535 tk = ExperimentalToolkit(slug="MY_TK", name="My TK", description="Desc")
536
537 @tk.tool()
538 def tool_a(input: GrepInput, ctx):
539 """Tool A."""
540 return {}
541
542 @tk.tool()
543 def tool_b(input: GrepInput, ctx):
544 """Tool B."""
545 return {}
546
547 assert tk.slug == "MY_TK"
548 assert len(tk.tools) == 2
549 assert tk.tools[0].slug == "TOOL_A"
550 assert tk.tools[1].slug == "TOOL_B"
551
552 def test_toolkit_bare_decorator(self):
553 tk = ExperimentalToolkit(slug="TK2", name="TK2", description="Desc")
554
555 @tk.tool
556 def tool_c(input: GrepInput, ctx):
557 """Tool C."""
558 return {}
559
560 assert len(tk.tools) == 1
561
562 def test_toolkit_slug_validation(self):
563 with pytest.raises(ValidationError, match="LOCAL_"):
564 ExperimentalToolkit(slug="LOCAL_BAD", name="Bad", description="Desc")
565
566 def test_toolkit_name_required(self):
567 with pytest.raises(ValidationError, match="name is required"):
568 ExperimentalToolkit(slug="TK", name="", description="Desc")
569
570 def test_toolkit_via_experimental_api(self):
571 tk = exp.Toolkit(slug="API_TK", name="API TK", description="Via API")
572 assert isinstance(tk, ExperimentalToolkit)
573 assert tk.slug == "API_TK"
574
575
576 # ────────────────────────────────────────────────────────────────
577 # Serialization tests
578 # ────────────────────────────────────────────────────────────────
579
580
581 class TestSerialization:
582 def test_serialize_standalone_tool(self, grep_tool):
583 result = serialize_custom_tools([grep_tool])
584 assert len(result) == 1
585 assert result[0]["slug"] == "GREP"
586 assert result[0]["input_schema"]["type"] == "object"
587 assert "extends_toolkit" not in result[0]
588
589 def test_serialize_extension_tool(self, email_tool):
590 result = serialize_custom_tools([email_tool])
591 assert result[0]["extends_toolkit"] == "gmail"
592
593 def test_serialize_custom_tool_preload_hint(self, grep_tool):
594 preloaded = replace(grep_tool, preload=True)
595 result = serialize_custom_tools([preloaded])
596 assert result[0]["preload"] is True
597
598 def test_serialize_custom_tool_omits_redundant_preload_false(self, grep_tool):
599 search_only = replace(grep_tool, preload=False)
600 result = serialize_custom_tools([search_only])
601 assert "preload" not in result[0]
602
603 def test_serialize_toolkit(self, role_toolkit):
604 result = serialize_custom_toolkits([role_toolkit])
605 assert len(result) == 1
606 assert result[0]["slug"] == "ROLE_MANAGER"
607 assert len(result[0]["tools"]) == 1
608
609 def test_serialize_toolkit_preload_hint(self, role_toolkit):
610 role_toolkit.preload = True
611 result = serialize_custom_toolkits([role_toolkit])
612 assert result[0]["preload"] is True
613 assert result[0]["tools"][0]["preload"] is True
614
615
616 # ────────────────────────────────────────────────────────────────
617 # Routing map tests
618 # ────────────────────────────────────────────────────────────────
619
620
621 class TestCustomToolsMap:
622 def test_build_map_standalone(self, grep_tool):
623 m = build_custom_tools_map([grep_tool])
624 assert "LOCAL_GREP" in m.by_final_slug
625
626 def test_build_map_extension(self, email_tool):
627 m = build_custom_tools_map([email_tool])
628 assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
629
630 def test_build_map_toolkit(self, role_toolkit):
631 m = build_custom_tools_map([], [role_toolkit])
632 assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
633
634 def test_allows_same_slug_in_different_toolkits(self, duplicate_slug_tools):
635 alpha_tool, beta_tool = duplicate_slug_tools
636 alpha = ExperimentalToolkit(
637 slug="ALPHA", name="Alpha", description="Alpha tools"
638 )
639 alpha._tools.append(alpha_tool)
640 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
641 beta._tools.append(beta_tool)
642
643 m = build_custom_tools_map([], [alpha, beta])
644
645 assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP", "LOCAL_BETA_GREP"}
646 assert "GREP" not in m.by_original_slug
647 assert m.ambiguous_original_slugs == {"GREP"}
648
649 def test_ambiguous_original_slug_requires_final_slug(self, duplicate_slug_tools):
650 alpha_tool, beta_tool = duplicate_slug_tools
651 alpha = ExperimentalToolkit(
652 slug="ALPHA", name="Alpha", description="Alpha tools"
653 )
654 alpha._tools.append(alpha_tool)
655 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
656 beta._tools.append(beta_tool)
657 m = build_custom_tools_map([], [alpha, beta])
658
659 assert find_custom_tool(m, "LOCAL_ALPHA_GREP").toolkit == "ALPHA"
660 assert find_custom_tool(m, "LOCAL_BETA_GREP").toolkit == "BETA"
661 assert find_custom_tool(m, "GREP") is None
662 with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):
663 assert_unambiguous_custom_tool_slug(m, "GREP")
664
665 def test_preload_rejects_ambiguous_original_slug(self, duplicate_slug_tools):
666 alpha_tool, beta_tool = duplicate_slug_tools
667 alpha = ExperimentalToolkit(
668 slug="ALPHA", name="Alpha", description="Alpha tools"
669 )
670 alpha._tools.append(alpha_tool)
671 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
672 beta._tools.append(beta_tool)
673 m = build_custom_tools_map([], [alpha, beta])
674
675 with pytest.raises(ValidationError, match="not supported in preload.tools"):
676 assert_no_custom_tool_slugs_in_preload(["grep"], m)
677
678 def test_collision_detection(self, grep_tool):
679 with pytest.raises(ValidationError, match="collision"):
680 build_custom_tools_map([grep_tool, grep_tool])
681
682 def test_rejects_standalone_and_toolkit_same_slug(self, duplicate_slug_tools):
683 alpha_tool, beta_tool = duplicate_slug_tools
684 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
685 beta._tools.append(beta_tool)
686
687 with pytest.raises(ValidationError, match="collision"):
688 build_custom_tools_map([alpha_tool], [beta])
689
690
691 class TestFindCustomTool:
692 def test_find_by_final_slug(self, grep_tool):
693 m = build_custom_tools_map([grep_tool])
694 assert find_custom_tool(m, "LOCAL_GREP") is not None
695
696 def test_find_case_insensitive(self, grep_tool):
697 m = build_custom_tools_map([grep_tool])
698 assert find_custom_tool(m, "grep") is not None
699
700 def test_find_nonexistent(self, grep_tool):
701 m = build_custom_tools_map([grep_tool])
702 assert find_custom_tool(m, "NONEXISTENT") is None
703
704 def test_find_none_map(self):
705 assert find_custom_tool(None, "GREP") is None
706
707
708 class TestBuildMapFromResponse:
709 def test_builds_from_response(self, grep_tool, email_tool, role_toolkit):
710 mock_exp = MagicMock()
711 mock_ct1 = MagicMock(
712 slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None
713 )
714 mock_ct2 = MagicMock(
715 slug="LOCAL_GMAIL_GET_EMAILS",
716 original_slug="GET_EMAILS",
717 extends_toolkit="gmail",
718 )
719 mock_exp.custom_tools = [mock_ct1, mock_ct2]
720 mock_ctk = MagicMock(slug="ROLE_MANAGER")
721 mock_ctk.tools = [
722 MagicMock(slug="LOCAL_ROLE_MANAGER_SET_ROLE", original_slug="SET_ROLE")
723 ]
724 mock_exp.custom_toolkits = [mock_ctk]
725
726 m = build_custom_tools_map_from_response(
727 [grep_tool, email_tool], [role_toolkit], mock_exp
728 )
729 assert "LOCAL_GREP" in m.by_final_slug
730 assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
731 assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
732
733 def test_allows_same_slug_in_different_toolkits(self, duplicate_slug_tools):
734 alpha_tool, beta_tool = duplicate_slug_tools
735 alpha = ExperimentalToolkit(
736 slug="ALPHA", name="Alpha", description="Alpha tools"
737 )
738 alpha._tools.append(alpha_tool)
739 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
740 beta._tools.append(beta_tool)
741 mock_exp = MagicMock()
742 mock_exp.custom_tools = []
743 mock_exp.custom_toolkits = [
744 MagicMock(
745 slug="ALPHA",
746 tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],
747 ),
748 MagicMock(
749 slug="BETA",
750 tools=[MagicMock(slug="LOCAL_BETA_GREP", original_slug="GREP")],
751 ),
752 ]
753
754 m = build_custom_tools_map_from_response([], [alpha, beta], mock_exp)
755
756 assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP", "LOCAL_BETA_GREP"}
757 assert m.by_final_slug["LOCAL_ALPHA_GREP"].toolkit == "ALPHA"
758 assert m.by_final_slug["LOCAL_BETA_GREP"].toolkit == "BETA"
759 assert m.ambiguous_original_slugs == {"GREP"}
760
761 def _duplicate_toolkits(self, duplicate_slug_tools):
762 alpha_tool, beta_tool = duplicate_slug_tools
763 alpha = ExperimentalToolkit(
764 slug="ALPHA", name="Alpha", description="Alpha tools"
765 )
766 alpha._tools.append(alpha_tool)
767 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
768 beta._tools.append(beta_tool)
769 return alpha, beta
770
771 def test_rejects_toolkit_child_without_exact_match(self, duplicate_slug_tools):
772 alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)
773 mock_exp = MagicMock()
774 mock_exp.custom_tools = []
775 mock_exp.custom_toolkits = [
776 MagicMock(
777 slug="GAMMA",
778 tools=[MagicMock(slug="LOCAL_GAMMA_GREP", original_slug="GREP")],
779 ),
780 ]
781
782 with pytest.raises(ValidationError, match="no exact local match"):
783 build_custom_tools_map_from_response([], [alpha, beta], mock_exp)
784
785 def test_never_binds_toolkit_child_to_another_toolkit(self, duplicate_slug_tools):
786 alpha_tool, _ = duplicate_slug_tools
787 alpha = ExperimentalToolkit(
788 slug="ALPHA", name="Alpha", description="Alpha tools"
789 )
790 alpha._tools.append(alpha_tool)
791 mock_exp = MagicMock()
792 mock_exp.custom_tools = []
793 mock_exp.custom_toolkits = [
794 MagicMock(
795 slug="BETA",
796 tools=[MagicMock(slug="LOCAL_BETA_GREP", original_slug="GREP")],
797 ),
798 ]
799
800 with pytest.raises(ValidationError, match='for toolkit "BETA"'):
801 build_custom_tools_map_from_response([], [alpha], mock_exp)
802
803 def test_standalone_falls_back_to_unique_bare_match(self, email_tool):
804 mock_exp = MagicMock()
805 mock_exp.custom_tools = [
806 MagicMock(
807 slug="LOCAL_GMAIL_GET_EMAILS",
808 original_slug="GET_EMAILS",
809 extends_toolkit=None,
810 )
811 ]
812 mock_exp.custom_toolkits = []
813
814 m = build_custom_tools_map_from_response([email_tool], None, mock_exp)
815
816 assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"
817
818 def test_skips_response_tools_not_defined_locally(self, grep_tool):
819 mock_exp = MagicMock()
820 mock_exp.custom_tools = [
821 MagicMock(slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None),
822 MagicMock(slug="LOCAL_STALE", original_slug="STALE", extends_toolkit=None),
823 ]
824 mock_exp.custom_toolkits = []
825
826 m = build_custom_tools_map_from_response([grep_tool], None, mock_exp)
827
828 assert set(m.by_final_slug) == {"LOCAL_GREP"}
829
830 def test_ambiguity_follows_local_definitions(self, duplicate_slug_tools):
831 alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)
832 mock_exp = MagicMock()
833 mock_exp.custom_tools = []
834 mock_exp.custom_toolkits = [
835 MagicMock(
836 slug="ALPHA",
837 tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],
838 ),
839 ]
840
841 m = build_custom_tools_map_from_response([], [alpha, beta], mock_exp)
842
843 assert set(m.by_final_slug) == {"LOCAL_ALPHA_GREP"}
844 assert "GREP" not in m.by_original_slug
845 assert m.ambiguous_original_slugs == {"GREP"}
846 assert find_custom_tool(m, "GREP") is None
847
848 def test_rejects_duplicate_qualified_response_entries(self, duplicate_slug_tools):
849 alpha, beta = self._duplicate_toolkits(duplicate_slug_tools)
850 mock_exp = MagicMock()
851 mock_exp.custom_tools = []
852 mock_exp.custom_toolkits = [
853 MagicMock(
854 slug="ALPHA",
855 tools=[
856 MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP"),
857 MagicMock(slug="LOCAL_ALPHA_GREP_2", original_slug="GREP"),
858 ],
859 ),
860 ]
861
862 with pytest.raises(ValidationError, match="already registered for toolkit"):
863 build_custom_tools_map_from_response([], [alpha, beta], mock_exp)
864
865
866 # ────────────────────────────────────────────────────────────────
867 # Execution tests
868 # ────────────────────────────────────────────────────────────────
869
870
871 class TestExecuteCustomTool:
872 def test_successful_execution(self, grep_tool):
873 m = build_custom_tools_map([grep_tool])
874 entry = find_custom_tool(m, "GREP")
875 result = execute_custom_tool(entry, {"pattern": "hello"}, MockSessionContext()) # type: ignore
876 assert result["successful"] is True
877 assert result["data"]["matches"] == ["hello"]
878
879 def test_validation_failure(self, grep_tool):
880 m = build_custom_tools_map([grep_tool])
881 entry = find_custom_tool(m, "GREP")
882 result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore
883 assert result["successful"] is False
884
885 def test_execute_error(self):
886 @exp.tool()
887 def bad(input: GrepInput, ctx):
888 """Bad."""
889 raise RuntimeError("boom")
890
891 m = build_custom_tools_map([bad])
892 entry = find_custom_tool(m, "BAD")
893 result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
894 assert result["successful"] is False
895 assert "boom" in result["error"]
896
897
898 # ────────────────────────────────────────────────────────────────
899 # SessionContextImpl tests
900 # ────────────────────────────────────────────────────────────────
901
902
903 class TestSessionContextImpl:
904 def test_sibling_routing(self, grep_tool):
905 m = build_custom_tools_map([grep_tool])
906 ctx = SessionContextImpl(
907 client=mock_http_client(MagicMock),
908 user_id="u",
909 session_id="s",
910 custom_tools_map=m,
911 )
912 result = ctx.execute("GREP", {"pattern": "test"})
913 assert isinstance(result, SessionExecuteResponse)
914 assert result.error is None
915 assert result.log_id == ""
916 assert result.data["matches"] == ["test"]
917
918 def test_sibling_routing_rejects_ambiguous_slug(self, duplicate_slug_tools):
919 alpha_tool, beta_tool = duplicate_slug_tools
920 alpha = ExperimentalToolkit(
921 slug="ALPHA", name="Alpha", description="Alpha tools"
922 )
923 alpha._tools.append(alpha_tool)
924 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
925 beta._tools.append(beta_tool)
926 m = build_custom_tools_map([], [alpha, beta])
927 mock_client = mock_http_client(MagicMock)
928 ctx = SessionContextImpl(
929 client=mock_client, user_id="u", session_id="s", custom_tools_map=m
930 )
931
932 with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):
933 ctx.execute("GREP", {"pattern": "x"})
934 mock_client.tool_router.session.execute.assert_not_called()
935
936 result = ctx.execute("LOCAL_BETA_GREP", {"pattern": "x"})
937 assert result.data["toolkit"] == "beta"
938
939 def test_remote_fallback(self, grep_tool):
940 m = build_custom_tools_map([grep_tool])
941 mock_client = mock_http_client(MagicMock)
942 mock_client.tool_router.session.execute.return_value = SessionExecuteResponse(
943 data={"remote": True}, error=None, log_id="log_123", result_type="completed"
944 )
945 ctx = SessionContextImpl(
946 client=mock_client, user_id="u", session_id="s", custom_tools_map=m
947 )
948 ctx.execute("NONEXISTENT", {"arg": "val"})
949 mock_client.tool_router.session.execute.assert_called_once_with(
950 session_id="s",
951 tool_slug="NONEXISTENT",
952 arguments={"arg": "val"},
953 experimental=omit,
954 )
955
956 def test_remote_fallback_passes_inline_custom_tools(self):
957 mock_client = mock_http_client(MagicMock)
958 mock_client.tool_router.session.execute.return_value = SessionExecuteResponse(
959 data={"remote": True}, error=None, log_id="log_123", result_type="completed"
960 )
961 inline_payload = {
962 "custom_tools": [
963 {
964 "slug": "GREP",
965 "name": "Grep",
966 "description": "Search local text",
967 "input_schema": {"type": "object", "properties": {}},
968 }
969 ]
970 }
971 ctx = SessionContextImpl(
972 client=mock_client,
973 user_id="u",
974 session_id="s",
975 inline_custom_tools_payload=inline_payload,
976 )
977 ctx.execute("GMAIL_SEND_EMAIL", {"to": "a@b.com"})
978 mock_client.tool_router.session.execute.assert_called_once_with(
979 session_id="s",
980 tool_slug="GMAIL_SEND_EMAIL",
981 arguments={"to": "a@b.com"},
982 experimental=inline_payload,
983 )
984
985 def test_proxy_execute(self):
986 mock_client = mock_http_client(MagicMock)
987 mock_client.tool_router.session.proxy_execute.return_value = (
988 SessionProxyExecuteResponse(
989 status=200, data={"ok": True}, headers={}, binary_data=None
990 )
991 )
992 ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
993 result = ctx.proxy_execute(
994 toolkit="gmail", endpoint="https://example.com", method="GET"
995 )
996 assert result == {
997 "result_type": "completed",
998 "status": 200,
999 "data": {"ok": True},
1000 "headers": {},
1001 }
1002 assert "binary_data" not in result
1003
1004 def test_proxy_execute_narrows_status_to_int(self):
1005 """The generated model types ``status`` as ``float`` and pydantic coerces.
1006
1007 Equality alone cannot catch the leak, because ``200 == 200.0``. Only the
1008 type assertion distinguishes ``200`` from the ``200.0`` a raw read returns.
1009 """
1010 mock_client = mock_http_client(MagicMock)
1011 mock_client.tool_router.session.proxy_execute.return_value = (
1012 SessionProxyExecuteResponse(
1013 status=200, data=None, headers=None, binary_data=None
1014 )
1015 )
1016 ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
1017 result = ctx.proxy_execute(
1018 toolkit="gmail", endpoint="https://example.com", method="GET"
1019 )
1020 assert result["result_type"] == "completed"
1021 assert isinstance(result["status"], int)
1022 assert result == {
1023 "result_type": "completed",
1024 "status": 200,
1025 "data": None,
1026 "headers": None,
1027 }
1028
1029 def test_proxy_execute_projects_binary_data(self):
1030 mock_client = mock_http_client(MagicMock)
1031 mock_client.tool_router.session.proxy_execute.return_value = (
1032 SessionProxyExecuteResponse(
1033 status=200,
1034 data={"ok": True},
1035 headers={"content-type": "application/pdf"},
1036 binary_data=BinaryData(
1037 content_type="application/pdf",
1038 size=123,
1039 url="https://example.com/file.pdf",
1040 expires_at="2026-08-18T00:00:00Z",
1041 ),
1042 )
1043 )
1044 ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
1045 result = ctx.proxy_execute(
1046 toolkit="gmail", endpoint="https://example.com", method="GET"
1047 )
1048 assert result == {
1049 "result_type": "completed",
1050 "status": 200,
1051 "data": {"ok": True},
1052 "headers": {"content-type": "application/pdf"},
1053 "binary_data": {
1054 "content_type": "application/pdf",
1055 "size": 123,
1056 "url": "https://example.com/file.pdf",
1057 "expires_at": "2026-08-18T00:00:00Z",
1058 },
1059 }
1060 assert isinstance(result["binary_data"]["size"], int)
1061
1062 def test_proxy_execute_binary_data_without_expiry(self):
1063 """``expires_at`` is optional on the generated model; the key stays present."""
1064 mock_client = mock_http_client(MagicMock)
1065 mock_client.tool_router.session.proxy_execute.return_value = (
1066 SessionProxyExecuteResponse(
1067 status=200,
1068 data=None,
1069 headers=None,
1070 binary_data=BinaryData(
1071 content_type="image/png",
1072 size=7,
1073 url="https://example.com/file.png",
1074 ),
1075 )
1076 )
1077 ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
1078 result = ctx.proxy_execute(
1079 toolkit="gmail", endpoint="https://example.com", method="GET"
1080 )
1081 assert result["binary_data"] == {
1082 "content_type": "image/png",
1083 "size": 7,
1084 "url": "https://example.com/file.png",
1085 "expires_at": None,
1086 }
1087
1088
1089 # ────────────────────────────────────────────────────────────────
1090 # ToolRouterSession integration
1091 # ────────────────────────────────────────────────────────────────
1092
1093
1094 @pytest.fixture
1095 def mock_session_deps(grep_tool, email_tool, role_toolkit):
1096 return {
1097 "client": mock_http_client(MagicMock),
1098 "provider": MagicMock(),
1099 "experimental": MagicMock(),
1100 "tools_map": build_custom_tools_map([grep_tool, email_tool], [role_toolkit]),
1101 }
1102
1103
1104 def _session(deps, **overrides):
1105 kwargs = dict(
1106 client=deps["client"],
1107 provider=deps["provider"],
1108 dangerously_allow_auto_upload_download_files=True,
1109 session_id="s",
1110 mcp=MagicMock(),
1111 experimental=deps["experimental"],
1112 custom_tools_map=deps["tools_map"],
1113 user_id="u",
1114 )
1115 kwargs.update(overrides)
1116 return ToolRouterSession(**kwargs)
1117
1118
1119 class TestToolRouterSessionCustomTools:
1120 def test_execute_local_failure_without_message_is_failed(self):
1121 @exp.tool()
1122 def silent(input: GrepInput, ctx):
1123 """Raises an error with no message."""
1124 raise RuntimeError("")
1125
1126 s = ToolRouterSession(
1127 client=mock_http_client(MagicMock),
1128 provider=MagicMock(),
1129 dangerously_allow_auto_upload_download_files=True,
1130 session_id="s",
1131 mcp=MagicMock(),
1132 experimental=MagicMock(),
1133 custom_tools_map=build_custom_tools_map([silent]),
1134 user_id="u",
1135 )
1136
1137 result = s.execute("SILENT", arguments={"pattern": "x"})
1138
1139 assert result.error == ""
1140 assert result.result_type == "failed"
1141
1142 def test_execute_local(self, mock_session_deps):
1143 s = _session(mock_session_deps)
1144 result = s.execute("GREP", arguments={"pattern": "x"})
1145 # Returns SessionExecuteResponse — same type as remote
1146 assert isinstance(result, SessionExecuteResponse)
1147 assert result.error is None
1148 assert result.log_id == ""
1149 assert result.result_type == "completed"
1150 assert result.data["matches"] == ["x"]
1151 mock_session_deps["client"].tool_router.session.execute.assert_not_called()
1152
1153 def test_execute_remote(self, mock_session_deps):
1154 mock_response = SessionExecuteResponse(
1155 data={"sent": True}, error=None, log_id="log_123", result_type="completed"
1156 )
1157 mock_session_deps[
1158 "client"
1159 ].tool_router.session.execute.return_value = mock_response
1160 s = _session(mock_session_deps)
1161 result = s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
1162 mock_session_deps["client"].tool_router.session.execute.assert_called_once()
1163 call_args = mock_session_deps["client"].tool_router.session.execute.call_args
1164 assert call_args.kwargs["session_id"] == "s"
1165 assert call_args.kwargs["tool_slug"] == "GMAIL_SEND_EMAIL"
1166 assert call_args.kwargs["arguments"] == {"to": "a@b.com"}
1167 assert "extra_body" not in call_args.kwargs
1168 assert "enable_auto_workbench_offload" not in call_args.kwargs
1169 # Remote returns client model as-is (backward compat, supports attribute access)
1170 assert isinstance(result, SessionExecuteResponse)
1171 assert result.data == {"sent": True}
1172 assert result.log_id == "log_123"
1173
1174 def test_execute_remote_exposes_instant_charge(self, mock_session_deps):
1175 charge = {"amount": "0.01", "currency": "USD", "charged_by": "composio"}
1176 mock_session_deps[
1177 "client"
1178 ].tool_router.session.execute.return_value = (
1179 SessionExecuteResponse.model_validate(
1180 {
1181 "result_type": "completed",
1182 "data": {"sent": True},
1183 "error": None,
1184 "log_id": "log_123",
1185 "instant_charge": charge,
1186 }
1187 )
1188 )
1189 s = _session(mock_session_deps)
1190
1191 result = s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
1192
1193 assert isinstance(result, ToolRouterSessionExecuteResponse)
1194 assert isinstance(result, SessionExecuteResponse)
1195 assert result.instant_charge is not None
1196 assert result.instant_charge.model_dump() == charge
1197 assert result.data == {"sent": True}
1198 assert result.log_id == "log_123"
1199
1200 def test_execute_remote_without_instant_charge(self, mock_session_deps):
1201 mock_session_deps[
1202 "client"
1203 ].tool_router.session.execute.return_value = SessionExecuteResponse(
1204 data={"sent": True}, error=None, log_id="log_123", result_type="completed"
1205 )
1206 s = _session(mock_session_deps)
1207
1208 result = s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
1209
1210 assert result.instant_charge is None
1211
1212 def test_execute_remote_passes_inline_custom_tools(self, mock_session_deps):
1213 mock_response = SessionExecuteResponse(
1214 data={"sent": True}, error=None, log_id="log_123", result_type="completed"
1215 )
1216 mock_session_deps[
1217 "client"
1218 ].tool_router.session.execute.return_value = mock_response
1219 inline_payload = {
1220 "custom_tools": [
1221 {
1222 "slug": "GREP",
1223 "name": "Grep",
1224 "description": "Search local text",
1225 "input_schema": {"type": "object", "properties": {}},
1226 }
1227 ]
1228 }
1229 s = _session(mock_session_deps, inline_custom_tools_payload=inline_payload)
1230 s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
1231
1232 call_args = mock_session_deps["client"].tool_router.session.execute.call_args
1233 assert call_args.kwargs["experimental"] == inline_payload
1234
1235 def test_proxy_execute(self, mock_session_deps):
1236 mock_session_deps[
1237 "client"
1238 ].tool_router.session.proxy_execute.return_value = SessionProxyExecuteResponse(
1239 status=200, data={"ok": True}, headers={}, binary_data=None
1240 )
1241 s = _session(mock_session_deps)
1242 result = s.proxy_execute(
1243 toolkit="gmail", endpoint="https://example.com", method="GET"
1244 )
1245 assert result == {
1246 "result_type": "completed",
1247 "status": 200,
1248 "data": {"ok": True},
1249 "headers": {},
1250 }
1251 assert result["result_type"] == "completed"
1252 assert isinstance(result["status"], int)
1253 assert "binary_data" not in result
1254
1255 def test_proxy_execute_projects_binary_data(self, mock_session_deps):
1256 mock_session_deps[
1257 "client"
1258 ].tool_router.session.proxy_execute.return_value = SessionProxyExecuteResponse(
1259 status=200,
1260 data={"ok": True},
1261 headers={"content-type": "application/pdf"},
1262 binary_data=BinaryData(
1263 content_type="application/pdf",
1264 size=123,
1265 url="https://example.com/file.pdf",
1266 expires_at="2026-08-18T00:00:00Z",
1267 ),
1268 )
1269 s = _session(mock_session_deps)
1270 result = s.proxy_execute(
1271 toolkit="gmail", endpoint="https://example.com", method="GET"
1272 )
1273 assert result == {
1274 "result_type": "completed",
1275 "status": 200,
1276 "data": {"ok": True},
1277 "headers": {"content-type": "application/pdf"},
1278 "binary_data": {
1279 "content_type": "application/pdf",
1280 "size": 123,
1281 "url": "https://example.com/file.pdf",
1282 "expires_at": "2026-08-18T00:00:00Z",
1283 },
1284 }
1285 assert isinstance(result["binary_data"]["size"], int)
1286
1287 def test_custom_tools_list(self, mock_session_deps):
1288 s = _session(mock_session_deps)
1289 assert len(s.local_tools()) == 3
1290
1291 def test_custom_tools_filter(self, mock_session_deps):
1292 s = _session(mock_session_deps)
1293 assert len(s.local_tools(toolkit="gmail")) == 1
1294
1295 def test_custom_toolkits_list(self, mock_session_deps):
1296 s = _session(mock_session_deps)
1297 tks = s.local_toolkits()
1298 assert len(tks) == 1
1299 assert tks[0].slug == "ROLE_MANAGER"
1300
1301 def test_custom_toolkits_list_uses_qualified_slugs(self, duplicate_slug_tools):
1302 alpha_tool, beta_tool = duplicate_slug_tools
1303 alpha = ExperimentalToolkit(
1304 slug="ALPHA", name="Alpha", description="Alpha tools"
1305 )
1306 alpha._tools.append(alpha_tool)
1307 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
1308 beta._tools.append(beta_tool)
1309 custom_tools_map = build_custom_tools_map([], [alpha, beta])
1310 s = ToolRouterSession(
1311 client=mock_http_client(MagicMock),
1312 provider=MagicMock(),
1313 dangerously_allow_auto_upload_download_files=True,
1314 session_id="s",
1315 mcp=MagicMock(),
1316 experimental=MagicMock(),
1317 custom_tools_map=custom_tools_map,
1318 user_id="u",
1319 )
1320
1321 toolkits = s.local_toolkits()
1322
1323 assert [tk.tools[0].slug for tk in toolkits] == [
1324 "LOCAL_ALPHA_GREP",
1325 "LOCAL_BETA_GREP",
1326 ]
1327
1328 def test_custom_toolkits_list_never_borrows_other_toolkit_slug(
1329 self, duplicate_slug_tools
1330 ):
1331 alpha_tool, beta_tool = duplicate_slug_tools
1332 alpha = ExperimentalToolkit(
1333 slug="ALPHA", name="Alpha", description="Alpha tools"
1334 )
1335 alpha._tools.append(alpha_tool)
1336 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
1337 beta._tools.append(beta_tool)
1338 mock_exp = MagicMock()
1339 mock_exp.custom_tools = []
1340 mock_exp.custom_toolkits = [
1341 MagicMock(
1342 slug="ALPHA",
1343 tools=[MagicMock(slug="LOCAL_ALPHA_GREP", original_slug="GREP")],
1344 ),
1345 ]
1346 custom_tools_map = build_custom_tools_map_from_response(
1347 [], [alpha, beta], mock_exp
1348 )
1349 s = ToolRouterSession(
1350 client=mock_http_client(MagicMock),
1351 provider=MagicMock(),
1352 dangerously_allow_auto_upload_download_files=True,
1353 session_id="s",
1354 mcp=MagicMock(),
1355 experimental=MagicMock(),
1356 custom_tools_map=custom_tools_map,
1357 user_id="u",
1358 )
1359
1360 assert [tk.tools[0].slug for tk in s.local_toolkits()] == [
1361 "LOCAL_ALPHA_GREP",
1362 "GREP",
1363 ]
1364
1365 def test_execute_rejects_ambiguous_original_slug(self, duplicate_slug_tools):
1366 alpha_tool, beta_tool = duplicate_slug_tools
1367 alpha = ExperimentalToolkit(
1368 slug="ALPHA", name="Alpha", description="Alpha tools"
1369 )
1370 alpha._tools.append(alpha_tool)
1371 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
1372 beta._tools.append(beta_tool)
1373 custom_tools_map = build_custom_tools_map([], [alpha, beta])
1374 client = mock_http_client(MagicMock)
1375 s = ToolRouterSession(
1376 client=client,
1377 provider=MagicMock(),
1378 dangerously_allow_auto_upload_download_files=True,
1379 session_id="s",
1380 mcp=MagicMock(),
1381 experimental=MagicMock(),
1382 custom_tools_map=custom_tools_map,
1383 user_id="u",
1384 )
1385
1386 with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):
1387 s.execute("GREP", arguments={"pattern": "x"})
1388 client.tool_router.session.execute.assert_not_called()
1389
1390 alpha_result = s.execute("LOCAL_ALPHA_GREP", arguments={"pattern": "x"})
1391 beta_result = s.execute("LOCAL_BETA_GREP", arguments={"pattern": "x"})
1392 assert alpha_result.data["toolkit"] == "alpha"
1393 assert beta_result.data["toolkit"] == "beta"
1394
1395 def test_empty_when_no_map(self):
1396 s = ToolRouterSession(
1397 client=mock_http_client(MagicMock),
1398 provider=MagicMock(),
1399 dangerously_allow_auto_upload_download_files=True,
1400 session_id="s",
1401 mcp=MagicMock(),
1402 experimental=MagicMock(),
1403 )
1404 assert s.local_tools() == []
1405
1406 def test_deprecated_custom_tools_matches_local_tools(self, mock_session_deps):
1407 s = _session(mock_session_deps)
1408
1409 with pytest.warns(
1410 ComposioDeprecationWarning,
1411 match=r"^`session\.custom_tools\(\)` is deprecated; use `session\.local_tools\(\)`$",
1412 ) as record:
1413 deprecated = s.custom_tools(toolkit="gmail")
1414
1415 assert record[0].filename == __file__
1416 assert deprecated == s.local_tools(toolkit="gmail")
1417 assert len(deprecated) == 1
1418
1419 def test_deprecated_custom_toolkits_matches_local_toolkits(self, mock_session_deps):
1420 s = _session(mock_session_deps)
1421
1422 with pytest.warns(
1423 ComposioDeprecationWarning,
1424 match=r"^`session\.custom_toolkits\(\)` is deprecated; use `session\.local_toolkits\(\)`$",
1425 ) as record:
1426 deprecated = s.custom_toolkits()
1427
1428 assert record[0].filename == __file__
1429 assert deprecated == s.local_toolkits()
1430 assert [tk.slug for tk in deprecated] == ["ROLE_MANAGER"]
1431
1432
1433 class TestLocalToolTypeNames:
1434 def test_new_names_import_without_warning(self):
1435 with warnings.catch_warnings():
1436 warnings.simplefilter("error")
1437 from composio import LocalTool, LocalToolkit
1438 from composio.core.models import (
1439 RegisteredLocalTool,
1440 RegisteredLocalToolkit,
1441 )
1442
1443 assert LocalTool is CustomTool
1444 assert LocalToolkit is ExperimentalToolkit
1445 assert RegisteredLocalTool is RegisteredCustomTool
1446 assert RegisteredLocalToolkit is RegisteredCustomToolkit
1447
1448 def test_deprecated_type_names_stay_plain_aliases(self):
1449 # Type names don't warn, so `from composio import *` stays quiet;
1450 # the deprecated options and session methods carry the warning.
1451 with warnings.catch_warnings():
1452 warnings.simplefilter("error")
1453 import composio
1454 from composio.core import models
1455
1456 assert composio.CustomTool is composio.LocalTool
1457 assert models.CustomTool is models.LocalTool
1458 assert models.RegisteredCustomTool is models.RegisteredLocalTool
1459 assert models.RegisteredCustomToolkit is models.RegisteredLocalToolkit
1460
1461
1462 # ────────────────────────────────────────────────────────────────
1463 # Multi-execute routing
1464 # ────────────────────────────────────────────────────────────────
1465
1466
1467 class TestMultiExecuteRouting:
1468 def _make_session(self, *tools, inline_custom_tools_payload=None):
1469 m = build_custom_tools_map(list(tools))
1470 return ToolRouterSession(
1471 client=mock_http_client(MagicMock),
1472 provider=MagicMock(),
1473 dangerously_allow_auto_upload_download_files=True,
1474 session_id="s",
1475 mcp=MagicMock(),
1476 experimental=MagicMock(),
1477 custom_tools_map=m,
1478 user_id="u",
1479 inline_custom_tools_payload=inline_custom_tools_payload,
1480 )
1481
1482 def test_single_local(self, grep_tool):
1483 s = self._make_session(grep_tool)
1484 result = s._route_multi_execute(
1485 {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "x"}}]},
1486 MagicMock(),
1487 )
1488 assert result["successful"] is True
1489 assert result["data"]["matches"] == ["x"]
1490
1491 def test_rejects_ambiguous_original_slug(self, duplicate_slug_tools):
1492 alpha_tool, beta_tool = duplicate_slug_tools
1493 alpha = ExperimentalToolkit(
1494 slug="ALPHA", name="Alpha", description="Alpha tools"
1495 )
1496 alpha._tools.append(alpha_tool)
1497 beta = ExperimentalToolkit(slug="BETA", name="Beta", description="Beta tools")
1498 beta._tools.append(beta_tool)
1499 s = ToolRouterSession(
1500 client=mock_http_client(MagicMock),
1501 provider=MagicMock(),
1502 dangerously_allow_auto_upload_download_files=True,
1503 session_id="s",
1504 mcp=MagicMock(),
1505 experimental=MagicMock(),
1506 custom_tools_map=build_custom_tools_map([], [alpha, beta]),
1507 user_id="u",
1508 )
1509 tm = MagicMock()
1510 backend = MagicMock()
1511 tm._wrap_execute_tool_for_tool_router.return_value = backend
1512
1513 with pytest.raises(ValidationError, match="Ambiguous custom tool slug"):
1514 s._route_multi_execute(
1515 {
1516 "tools": [
1517 {
1518 "tool_slug": "LOCAL_ALPHA_GREP",
1519 "arguments": {"pattern": "x"},
1520 },
1521 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1522 ]
1523 },
1524 tm,
1525 )
1526 backend.assert_not_called()
1527
1528 def test_all_remote(self, grep_tool):
1529 s = self._make_session(grep_tool)
1530 tm = MagicMock()
1531 remote = {"data": {"results": []}, "error": None, "successful": True}
1532 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1533 result = s._route_multi_execute(
1534 {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm
1535 )
1536 assert result == remote
1537
1538 def test_all_remote_passes_inline_custom_tools(self, grep_tool):
1539 inline_payload = {
1540 "custom_tools": [
1541 {
1542 "slug": "GREP",
1543 "name": "Grep",
1544 "description": "Search local text",
1545 "input_schema": {"type": "object", "properties": {}},
1546 }
1547 ]
1548 }
1549 s = self._make_session(grep_tool, inline_custom_tools_payload=inline_payload)
1550 tm = MagicMock()
1551 remote = {"data": {"results": []}, "error": None, "successful": True}
1552 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1553 s._route_multi_execute(
1554 {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm
1555 )
1556
1557 tm._wrap_execute_tool_for_tool_router.assert_called_once_with(
1558 session_id="s",
1559 modifiers=None,
1560 inline_custom_tools_payload=inline_payload,
1561 )
1562
1563 def test_mixed(self, grep_tool):
1564 s = self._make_session(grep_tool)
1565 tm = MagicMock()
1566 remote = {
1567 "data": {
1568 "results": [
1569 {"tool_slug": "R", "response": {"successful": True, "data": {}}},
1570 ],
1571 "total_count": 1,
1572 "success_count": 1,
1573 "error_count": 0,
1574 },
1575 "error": None,
1576 "successful": True,
1577 }
1578 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1579 result = s._route_multi_execute(
1580 {
1581 "tools": [
1582 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1583 {"tool_slug": "REMOTE", "arguments": {}},
1584 ]
1585 },
1586 tm,
1587 )
1588 results = result["data"]["results"]
1589 assert len(results) == 2
1590 # Results preserve the original request order.
1591 assert results[0]["tool_slug"] == "GREP"
1592 assert results[1]["tool_slug"] == "R"
1593 assert results[0]["index"] == 0
1594 assert results[1]["index"] == 1
1595 assert result["data"]["total_count"] == 2
1596 assert result["data"]["success_count"] == 2
1597 assert result["data"]["error_count"] == 0
1598 assert "instant_charge" not in result
1599
1600 def test_mixed_preserves_remote_instant_charge(self, grep_tool):
1601 s = self._make_session(grep_tool)
1602 tm = MagicMock()
1603 charge = {"amount": "0.01", "currency": "USD", "charged_by": "composio"}
1604 remote = {
1605 "data": {
1606 "results": [
1607 {"tool_slug": "R", "response": {"successful": True, "data": {}}},
1608 ],
1609 },
1610 "error": None,
1611 "successful": True,
1612 "instant_charge": charge,
1613 }
1614 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1615 result = s._route_multi_execute(
1616 {
1617 "tools": [
1618 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1619 {"tool_slug": "REMOTE", "arguments": {}},
1620 ]
1621 },
1622 tm,
1623 )
1624
1625 assert result["instant_charge"] == charge
1626
1627 def test_failure_propagated(self):
1628 @exp.tool()
1629 def ok_tool(input: GrepInput, ctx):
1630 """OK."""
1631 return {"ok": True}
1632
1633 @exp.tool()
1634 def bad_tool(input: GrepInput, ctx):
1635 """Bad."""
1636 raise RuntimeError("boom")
1637
1638 s = self._make_session(ok_tool, bad_tool)
1639 result = s._route_multi_execute(
1640 {
1641 "tools": [
1642 {"tool_slug": "OK_TOOL", "arguments": {"pattern": "x"}},
1643 {"tool_slug": "BAD_TOOL", "arguments": {"pattern": "y"}},
1644 ]
1645 },
1646 MagicMock(),
1647 )
1648 assert result["successful"] is False
1649 assert "1 out of 2" in result["error"]
1650
1651 def test_remote_null_data_does_not_crash(self, grep_tool):
1652 s = self._make_session(grep_tool)
1653 tm = MagicMock()
1654 remote = {"data": None, "error": None, "successful": True}
1655 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1656 result = s._route_multi_execute(
1657 {
1658 "tools": [
1659 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1660 {"tool_slug": "REMOTE", "arguments": {}},
1661 ]
1662 },
1663 tm,
1664 )
1665 assert result["successful"] is True
1666 assert result["data"]["results"][0]["tool_slug"] == "GREP"
1667
1668 def test_remote_transport_failure_keeps_local_results(self, grep_tool):
1669 """A raised backend error becomes per-tool failures (matches TS)."""
1670 s = self._make_session(grep_tool)
1671 tm = MagicMock()
1672
1673 def failing_backend(slug, args):
1674 raise RuntimeError("remote unavailable")
1675
1676 tm._wrap_execute_tool_for_tool_router.return_value = failing_backend
1677 result = s._route_multi_execute(
1678 {
1679 "tools": [
1680 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1681 {"tool_slug": "REMOTE", "arguments": {}},
1682 {"tool_slug": "OTHER_REMOTE", "arguments": {}},
1683 ]
1684 },
1685 tm,
1686 )
1687 assert result["successful"] is False
1688 assert result["error"] == "2 out of 3 tools failed"
1689 results = result["data"]["results"]
1690 assert [r["tool_slug"] for r in results] == ["GREP", "REMOTE", "OTHER_REMOTE"]
1691 assert [r["index"] for r in results] == [0, 1, 2]
1692 assert results[0]["response"] == {
1693 "successful": True,
1694 "data": {"matches": ["x"], "path": "."},
1695 }
1696 assert "error" not in results[0]
1697 for entry in results[1:]:
1698 assert entry["error"] == "remote unavailable"
1699 assert entry["response"] == {
1700 "successful": False,
1701 "data": {},
1702 "error": "remote unavailable",
1703 }
1704 assert result["data"]["total_count"] == 3
1705 assert result["data"]["success_count"] == 1
1706 assert result["data"]["error_count"] == 2
1707
1708 def test_remote_transport_failure_uses_fallback_message(self, grep_tool):
1709 s = self._make_session(grep_tool)
1710 tm = MagicMock()
1711
1712 def failing_backend(slug, args):
1713 raise RuntimeError()
1714
1715 tm._wrap_execute_tool_for_tool_router.return_value = failing_backend
1716 result = s._route_multi_execute(
1717 {
1718 "tools": [
1719 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1720 {"tool_slug": "REMOTE", "arguments": {}},
1721 ]
1722 },
1723 tm,
1724 )
1725 assert result["successful"] is False
1726 assert result["data"]["results"][1]["error"] == "Remote tool execution failed"
1727
1728 def test_failed_remote_batch_without_error_text_is_unsuccessful(self, grep_tool):
1729 s = self._make_session(grep_tool)
1730 tm = MagicMock()
1731 remote = {"data": {}, "error": None, "successful": False}
1732 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1733 result = s._route_multi_execute(
1734 {
1735 "tools": [
1736 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1737 {"tool_slug": "REMOTE", "arguments": {}},
1738 ]
1739 },
1740 tm,
1741 )
1742 assert result["successful"] is False
1743 assert result["error"] is None
1744
1745 def test_remote_batch_error_without_item_errors_uses_batch_message(self, grep_tool):
1746 s = self._make_session(grep_tool)
1747 tm = MagicMock()
1748 remote = {
1749 "data": None,
1750 "error": "Remote batch failed before per-tool results were produced",
1751 "successful": False,
1752 }
1753 tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
1754 result = s._route_multi_execute(
1755 {
1756 "tools": [
1757 {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
1758 {"tool_slug": "REMOTE", "arguments": {}},
1759 ]
1760 },
1761 tm,
1762 )
1763 assert result["successful"] is False
1764 assert (
1765 result["error"]
1766 == "Remote batch failed before per-tool results were produced"
1767 )