1
"""Tests for custom tools in tool router sessions.
2
3
Covers:
4
-- Factory function validation (slug rules, required fields, Pydantic model check)
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)
17
import pytest
18
from pydantic import BaseModel, Field
19
19
-from composio import experimental_create_tool, experimental_create_toolkit
20
from composio.core.models.custom_tool import (
21
+ ExperimentalAPI,
22
+ ExperimentalToolkit,
23
build_custom_tools_map,
24
build_custom_tools_map_from_response,
25
serialize_custom_tools,
38
# Fixtures
39
# ────────────────────────────────────────────────────────────────
40
41
+exp = ExperimentalAPI()
42
+
43
44
class GrepInput(BaseModel):
45
pattern: str = Field(description="Pattern to search for")
58
59
@pytest.fixture
60
def grep_tool():
57
- return experimental_create_tool(
58
- "GREP",
59
- name="Grep Search",
60
- description="Search for patterns in files",
61
- input_params=GrepInput,
62
- execute=lambda input, ctx: {"matches": [input.pattern], "path": input.path},
63
- )
61
+ @exp.tool()
62
+ def grep(input: GrepInput, ctx):
63
+ """Search for patterns in files."""
64
+ return {"matches": [input.pattern], "path": input.path}
65
+
66
+ return grep
67
68
69
@pytest.fixture
70
def email_tool():
68
- return experimental_create_tool(
69
- "GET_EMAILS",
70
- name="Get Emails",
71
- description="Get emails from Gmail",
72
- input_params=EmailInput,
73
- execute=lambda input, ctx: {"emails": []},
74
- extends_toolkit="gmail",
75
- )
71
+ @exp.tool(extends_toolkit="gmail")
72
+ def get_emails(input: EmailInput, ctx):
73
+ """Get emails from Gmail."""
74
+ return {"emails": []}
75
+
76
+ return get_emails
77
78
79
@pytest.fixture
80
def set_role_tool():
80
- return experimental_create_tool(
81
- "SET_ROLE",
82
- name="Set role",
83
- description="Set a user's role",
84
- input_params=SetRoleInput,
85
- execute=lambda input, ctx: {
86
- "user_id": input.user_id,
87
- "role": input.role,
88
- "updated": True,
89
- },
90
- )
81
+ @exp.tool()
82
+ def set_role(input: SetRoleInput, ctx):
83
+ """Set a user's role."""
84
+ return {"user_id": input.user_id, "role": input.role, "updated": True}
85
+
86
+ return set_role
87
88
89
@pytest.fixture
90
def role_toolkit(set_role_tool):
95
- return experimental_create_toolkit(
96
- "ROLE_MANAGER",
97
- name="Role Manager",
98
- description="Manage user roles",
99
- tools=[set_role_tool],
91
+ tk = ExperimentalToolkit(
92
+ slug="ROLE_MANAGER", name="Role Manager", description="Manage user roles"
93
)
94
+ tk._tools.append(set_role_tool)
95
+ return tk
96
97
98
class MockSessionContext:
106
107
108
# ────────────────────────────────────────────────────────────────
114
-# Factory validation tests
109
+# Decorator API tests
110
# ────────────────────────────────────────────────────────────────
111
112
118
-class TestCreateCustomTool:
119
- def test_creates_tool_with_valid_params(self, grep_tool):
120
- assert grep_tool.slug == "GREP"
121
- assert grep_tool.name == "Grep Search"
122
- assert grep_tool.description == "Search for patterns in files"
123
- assert grep_tool.extends_toolkit is None
124
- assert grep_tool.input_schema["type"] == "object"
125
- assert "pattern" in grep_tool.input_schema["properties"]
126
- assert grep_tool.output_schema is None
127
-
128
- def test_creates_extension_tool(self, email_tool):
129
- assert email_tool.slug == "GET_EMAILS"
130
- assert email_tool.extends_toolkit == "gmail"
131
-
132
- def test_slug_empty(self):
133
- with pytest.raises(ValidationError, match="slug is required"):
134
- experimental_create_tool(
135
- "",
136
- name="Bad",
137
- description="Bad",
138
- input_params=GrepInput,
139
- execute=lambda i, c: {},
140
- )
141
-
142
- def test_slug_invalid_chars(self):
143
- with pytest.raises(ValidationError, match="alphanumeric"):
144
- experimental_create_tool(
145
- "BAD SLUG!",
146
- name="Bad",
147
- description="Bad",
148
- input_params=GrepInput,
149
- execute=lambda i, c: {},
150
- )
151
-
152
- def test_slug_local_prefix(self):
153
- with pytest.raises(ValidationError, match="LOCAL_"):
154
- experimental_create_tool(
155
- "LOCAL_BAD",
156
- name="Bad",
157
- description="Bad",
158
- input_params=GrepInput,
159
- execute=lambda i, c: {},
160
- )
161
-
162
- def test_slug_composio_prefix(self):
163
- with pytest.raises(ValidationError, match="COMPOSIO_"):
164
- experimental_create_tool(
165
- "COMPOSIO_BAD",
166
- name="Bad",
167
- description="Bad",
168
- input_params=GrepInput,
169
- execute=lambda i, c: {},
170
- )
171
-
172
- def test_name_required(self):
173
- with pytest.raises(ValidationError, match="name is required"):
174
- experimental_create_tool(
175
- "GOOD",
176
- name="",
177
- description="Desc",
178
- input_params=GrepInput,
179
- execute=lambda i, c: {},
180
- )
181
-
182
- def test_description_required(self):
113
+class TestDecoratorTool:
114
+ def test_bare_decorator(self):
115
+ @exp.tool
116
+ def my_tool(input: GrepInput, ctx):
117
+ """My tool description."""
118
+ return {}
119
+
120
+ assert my_tool.slug == "MY_TOOL"
121
+ assert my_tool.name == "My Tool"
122
+ assert my_tool.description == "My tool description."
123
+ assert my_tool.input_schema["type"] == "object"
124
+ assert "pattern" in my_tool.input_schema["properties"]
125
+
126
+ def test_decorator_with_parens(self):
127
+ @exp.tool()
128
+ def search(input: GrepInput, ctx):
129
+ """Search stuff."""
130
+ return {}
131
+
132
+ assert search.slug == "SEARCH"
133
+
134
+ def test_decorator_with_extends_toolkit(self):
135
+ @exp.tool(extends_toolkit="gmail")
136
+ def fetch_mail(input: EmailInput, ctx):
137
+ """Fetch mail."""
138
+ return {}
139
+
140
+ assert fetch_mail.extends_toolkit == "gmail"
141
+
142
+ def test_decorator_explicit_overrides(self):
143
+ @exp.tool(slug="CUSTOM", name="Custom Name", description="Custom desc")
144
+ def whatever(input: GrepInput, ctx):
145
+ """Original docstring."""
146
+ return {}
147
+
148
+ assert whatever.slug == "CUSTOM"
149
+ assert whatever.name == "Custom Name"
150
+ assert whatever.description == "Custom desc"
151
+
152
+ def test_infers_from_function_name(self):
153
+ @exp.tool()
154
+ def search_user_by_email(input: GrepInput, ctx):
155
+ """Find a user."""
156
+ return {}
157
+
158
+ assert search_user_by_email.slug == "SEARCH_USER_BY_EMAIL"
159
+ assert search_user_by_email.name == "Search User By Email"
160
+
161
+ def test_infers_description_from_docstring(self):
162
+ @exp.tool()
163
+ def my_func(input: GrepInput, ctx):
164
+ """Trimmed docstring."""
165
+ return {}
166
+
167
+ assert my_func.description == "Trimmed docstring."
168
+
169
+ def test_missing_docstring_raises(self):
170
with pytest.raises(ValidationError, match="description is required"):
184
- experimental_create_tool(
185
- "GOOD",
186
- name="Name",
187
- description="",
188
- input_params=GrepInput,
189
- execute=lambda i, c: {},
190
- )
191
-
192
- def test_input_params_must_be_basemodel_subclass(self):
193
- with pytest.raises(ValidationError, match="BaseModel subclass"):
194
- experimental_create_tool(
195
- "GOOD",
196
- name="Name",
197
- description="Desc",
198
- input_params=dict, # type: ignore
199
- execute=lambda i, c: {},
200
- )
201
-
202
- def test_input_params_must_not_be_instance(self):
171
+
172
+ @exp.tool()
173
+ def no_doc(input: GrepInput, ctx):
174
+ return {}
175
+
176
+ def test_missing_basemodel_annotation_raises(self):
177
with pytest.raises(ValidationError, match="BaseModel subclass"):
204
- experimental_create_tool(
205
- "GOOD",
206
- name="Name",
207
- description="Desc",
208
- input_params=GrepInput(pattern="x"), # type: ignore
209
- execute=lambda i, c: {},
210
- )
211
-
212
- def test_execute_must_be_callable(self):
213
- with pytest.raises(ValidationError, match="callable"):
214
- experimental_create_tool(
215
- "GOOD",
216
- name="Name",
217
- description="Desc",
218
- input_params=GrepInput,
219
- execute="not a function", # type: ignore
220
- )
221
-
222
- def test_slug_length_validation_standalone(self):
223
- # LOCAL_ + 55 chars = 61 > 60
224
- with pytest.raises(ValidationError, match="too long"):
225
- experimental_create_tool(
226
- "A" * 55,
227
- name="Name",
228
- description="Desc",
229
- input_params=GrepInput,
230
- execute=lambda i, c: {},
231
- )
232
-
233
- def test_slug_length_validation_extension(self):
234
- # LOCAL_ + GMAIL_ + slug must be <= 60
235
- with pytest.raises(ValidationError, match="too long"):
236
- experimental_create_tool(
237
- "A" * 50,
238
- name="Name",
239
- description="Desc",
240
- input_params=GrepInput,
241
- execute=lambda i, c: {},
242
- extends_toolkit="gmail",
243
- )
244
-
245
- def test_output_params(self):
246
- class OutputSchema(BaseModel):
247
- matches: int
248
-
249
- tool = experimental_create_tool(
250
- "TOOL",
251
- name="Tool",
252
- description="Desc",
253
- input_params=GrepInput,
254
- execute=lambda i, c: {},
255
- output_params=OutputSchema,
256
- )
257
- assert tool.output_schema is not None
258
- assert "properties" in tool.output_schema
178
260
- def test_rejects_root_model(self):
179
+ @exp.tool()
180
+ def bad(x: str, ctx):
181
+ """Bad tool."""
182
+ return {}
183
+
184
+ def test_async_function_rejected(self):
185
+ with pytest.raises(ValidationError, match="synchronous"):
186
+
187
+ @exp.tool()
188
+ async def async_tool(input: GrepInput, ctx):
189
+ """Async tool."""
190
+ return {}
191
+
192
+ def test_root_model_rejected(self):
193
from pydantic import RootModel
194
195
class ListInput(RootModel[list[int]]):
196
pass
197
198
with pytest.raises(ValidationError, match="RootModel"):
267
- experimental_create_tool(
268
- "BAD",
269
- name="Bad",
270
- description="Desc",
271
- input_params=ListInput,
272
- execute=lambda i, c: {},
273
- )
274
-
275
- def test_rejects_async_execute(self):
276
- async def async_execute(input, ctx):
277
- return {"result": "ok"}
199
279
- with pytest.raises(ValidationError, match="synchronous"):
280
- experimental_create_tool(
281
- "ASYNC",
282
- name="Async",
283
- description="Desc",
284
- input_params=GrepInput,
285
- execute=async_execute,
286
- )
200
+ @exp.tool()
201
+ def bad(input: ListInput, ctx):
202
+ """Bad tool."""
203
+ return {}
204
+
205
+ def test_single_param_function(self):
206
+ """Function with only input param (no ctx) should work."""
207
+
208
+ @exp.tool()
209
+ def simple(input: GrepInput):
210
+ """Simple tool."""
211
+ return {"pattern": input.pattern}
212
+
213
+ m = build_custom_tools_map([simple])
214
+ entry = find_custom_tool(m, "SIMPLE")
215
+ result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
216
+ assert result["successful"] is True
217
+ assert result["data"]["pattern"] == "test"
218
+
219
+ def test_slug_validation(self):
220
+ with pytest.raises(ValidationError, match="LOCAL_"):
221
+
222
+ @exp.tool(slug="LOCAL_BAD")
223
+ def bad(input: GrepInput, ctx):
224
+ """Bad tool."""
225
+ return {}
226
+
227
+ def test_creates_frozen_custom_tool(self):
228
+ @exp.tool()
229
+ def frozen(input: GrepInput, ctx):
230
+ """Frozen tool."""
231
+ return {}
232
+
233
+ with pytest.raises(AttributeError):
234
+ frozen.slug = "NEW" # type: ignore
235
236
def test_input_schema_includes_defaults(self, grep_tool):
289
- # path has default="." - Pydantic won't include it in required
237
assert "pattern" in grep_tool.input_schema.get("required", [])
238
assert "path" not in grep_tool.input_schema.get("required", [])
239
293
- def test_frozen_dataclass(self, grep_tool):
294
- with pytest.raises(AttributeError):
295
- grep_tool.slug = "NEW" # type: ignore
296
-
297
-
298
-class TestCreateCustomToolkit:
299
- def test_creates_toolkit(self, role_toolkit, set_role_tool):
300
- assert role_toolkit.slug == "ROLE_MANAGER"
301
- assert role_toolkit.name == "Role Manager"
302
- assert len(role_toolkit.tools) == 1
303
- assert role_toolkit.tools[0].slug == "SET_ROLE"
304
-
305
- def test_rejects_empty_tools(self):
306
- with pytest.raises(ValidationError, match="at least one tool"):
307
- experimental_create_toolkit(
308
- "TK",
309
- name="TK",
310
- description="Desc",
311
- tools=[],
312
- )
313
-
314
- def test_rejects_extends_toolkit_in_tools(self, email_tool):
315
- with pytest.raises(ValidationError, match="extends_toolkit"):
316
- experimental_create_toolkit(
317
- "TK",
318
- name="TK",
319
- description="Desc",
320
- tools=[email_tool],
321
- )
322
-
323
- def test_slug_length_validation(self):
324
- tool = experimental_create_tool(
325
- "A" * 45,
326
- name="Name",
327
- description="Desc",
328
- input_params=GrepInput,
329
- execute=lambda i, c: {},
330
- )
331
- # LOCAL_ + LONG_TOOLKIT_ + AAAA... would exceed 60
332
- with pytest.raises(ValidationError, match="too long"):
333
- experimental_create_toolkit(
334
- "LONG_TOOLKIT",
335
- name="TK",
336
- description="Desc",
337
- tools=[tool],
338
- )
240
340
- def test_slug_validation(self):
241
+class TestToolkitBuilder:
242
+ def test_toolkit_with_decorator(self):
243
+ tk = ExperimentalToolkit(slug="MY_TK", name="My TK", description="Desc")
244
+
245
+ @tk.tool()
246
+ def tool_a(input: GrepInput, ctx):
247
+ """Tool A."""
248
+ return {}
249
+
250
+ @tk.tool()
251
+ def tool_b(input: GrepInput, ctx):
252
+ """Tool B."""
253
+ return {}
254
+
255
+ assert tk.slug == "MY_TK"
256
+ assert len(tk.tools) == 2
257
+ assert tk.tools[0].slug == "TOOL_A"
258
+ assert tk.tools[1].slug == "TOOL_B"
259
+
260
+ def test_toolkit_bare_decorator(self):
261
+ tk = ExperimentalToolkit(slug="TK2", name="TK2", description="Desc")
262
+
263
+ @tk.tool
264
+ def tool_c(input: GrepInput, ctx):
265
+ """Tool C."""
266
+ return {}
267
+
268
+ assert len(tk.tools) == 1
269
+
270
+ def test_toolkit_slug_validation(self):
271
with pytest.raises(ValidationError, match="LOCAL_"):
342
- experimental_create_toolkit(
343
- "LOCAL_BAD",
344
- name="TK",
345
- description="Desc",
346
- tools=[
347
- experimental_create_tool(
348
- "T",
349
- name="T",
350
- description="D",
351
- input_params=GrepInput,
352
- execute=lambda i, c: {},
353
- )
354
- ],
355
- )
272
+ ExperimentalToolkit(slug="LOCAL_BAD", name="Bad", description="Desc")
273
+
274
+ def test_toolkit_name_required(self):
275
+ with pytest.raises(ValidationError, match="name is required"):
276
+ ExperimentalToolkit(slug="TK", name="", description="Desc")
277
+
278
+ def test_toolkit_via_experimental_api(self):
279
+ tk = exp.Toolkit(slug="API_TK", name="API TK", description="Via API")
280
+ assert isinstance(tk, ExperimentalToolkit)
281
+ assert tk.slug == "API_TK"
282
283
284
# ────────────────────────────────────────────────────────────────
291
result = serialize_custom_tools([grep_tool])
292
assert len(result) == 1
293
assert result[0]["slug"] == "GREP"
368
- assert result[0]["name"] == "Grep Search"
294
assert result[0]["input_schema"]["type"] == "object"
295
assert "extends_toolkit" not in result[0]
296
303
assert len(result) == 1
304
assert result[0]["slug"] == "ROLE_MANAGER"
305
assert len(result[0]["tools"]) == 1
381
- assert result[0]["tools"][0]["slug"] == "SET_ROLE"
306
307
308
# ────────────────────────────────────────────────────────────────
314
def test_build_map_standalone(self, grep_tool):
315
m = build_custom_tools_map([grep_tool])
316
assert "LOCAL_GREP" in m.by_final_slug
393
- assert "GREP" in m.by_original_slug
317
318
def test_build_map_extension(self, email_tool):
319
m = build_custom_tools_map([email_tool])
320
assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
398
- assert "GET_EMAILS" in m.by_original_slug
321
400
- def test_build_map_toolkit(self, set_role_tool, role_toolkit):
322
+ def test_build_map_toolkit(self, role_toolkit):
323
m = build_custom_tools_map([], [role_toolkit])
324
assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
403
- assert "SET_ROLE" in m.by_original_slug
404
-
405
- def test_build_map_mixed(self, grep_tool, email_tool, role_toolkit):
406
- m = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
407
- assert len(m.by_final_slug) == 3
408
- assert len(m.by_original_slug) == 3
325
410
- def test_collision_detection_final_slug(self, grep_tool):
326
+ def test_collision_detection(self, grep_tool):
327
with pytest.raises(ValidationError, match="collision"):
328
build_custom_tools_map([grep_tool, grep_tool])
329
414
- def test_collision_detection_original_slug(self):
415
- tool1 = experimental_create_tool(
416
- "FOO",
417
- name="Foo",
418
- description="Desc",
419
- input_params=GrepInput,
420
- execute=lambda i, c: {},
421
- )
422
- # Same slug in a toolkit produces different final slug but same original
423
- # This would collide on original slug
424
- toolkit = experimental_create_toolkit(
425
- "TK",
426
- name="TK",
427
- description="D",
428
- tools=[
429
- experimental_create_tool(
430
- "FOO",
431
- name="Foo2",
432
- description="Desc2",
433
- input_params=GrepInput,
434
- execute=lambda i, c: {},
435
- )
436
- ],
437
- )
438
- with pytest.raises(ValidationError, match="collision"):
439
- build_custom_tools_map([tool1], [toolkit])
440
-
330
331
class TestFindCustomTool:
332
def test_find_by_final_slug(self, grep_tool):
333
m = build_custom_tools_map([grep_tool])
445
- entry = find_custom_tool(m, "LOCAL_GREP")
446
- assert entry is not None
447
- assert entry.final_slug == "LOCAL_GREP"
448
-
449
- def test_find_by_original_slug(self, grep_tool):
450
- m = build_custom_tools_map([grep_tool])
451
- entry = find_custom_tool(m, "GREP")
452
- assert entry is not None
453
- assert entry.final_slug == "LOCAL_GREP"
334
+ assert find_custom_tool(m, "LOCAL_GREP") is not None
335
336
def test_find_case_insensitive(self, grep_tool):
337
m = build_custom_tools_map([grep_tool])
457
- entry = find_custom_tool(m, "grep")
458
- assert entry is not None
459
- assert entry.final_slug == "LOCAL_GREP"
338
+ assert find_custom_tool(m, "grep") is not None
339
340
def test_find_nonexistent(self, grep_tool):
341
m = build_custom_tools_map([grep_tool])
347
348
class TestBuildMapFromResponse:
349
def test_builds_from_response(self, grep_tool, email_tool, role_toolkit):
471
- # Mock response experimental
350
mock_exp = MagicMock()
473
-
474
- mock_ct1 = MagicMock()
475
- mock_ct1.slug = "LOCAL_GREP"
476
- mock_ct1.original_slug = "GREP"
477
- mock_ct1.extends_toolkit = None
478
-
479
- mock_ct2 = MagicMock()
480
- mock_ct2.slug = "LOCAL_GMAIL_GET_EMAILS"
481
- mock_ct2.original_slug = "GET_EMAILS"
482
- mock_ct2.extends_toolkit = "gmail"
483
-
351
+ mock_ct1 = MagicMock(
352
+ slug="LOCAL_GREP", original_slug="GREP", extends_toolkit=None
353
+ )
354
+ mock_ct2 = MagicMock(
355
+ slug="LOCAL_GMAIL_GET_EMAILS",
356
+ original_slug="GET_EMAILS",
357
+ extends_toolkit="gmail",
358
+ )
359
mock_exp.custom_tools = [mock_ct1, mock_ct2]
485
-
486
- mock_ctk = MagicMock()
487
- mock_ctk.slug = "ROLE_MANAGER"
488
- mock_ctk_tool = MagicMock()
489
- mock_ctk_tool.slug = "LOCAL_ROLE_MANAGER_SET_ROLE"
490
- mock_ctk_tool.original_slug = "SET_ROLE"
491
- mock_ctk.tools = [mock_ctk_tool]
360
+ mock_ctk = MagicMock(slug="ROLE_MANAGER")
361
+ mock_ctk.tools = [
362
+ MagicMock(slug="LOCAL_ROLE_MANAGER_SET_ROLE", original_slug="SET_ROLE")
363
+ ]
364
mock_exp.custom_toolkits = [mock_ctk]
365
366
m = build_custom_tools_map_from_response(
495
- [grep_tool, email_tool],
496
- [role_toolkit],
497
- mock_exp,
367
+ [grep_tool, email_tool], [role_toolkit], mock_exp
368
)
499
-
369
assert "LOCAL_GREP" in m.by_final_slug
370
assert "LOCAL_GMAIL_GET_EMAILS" in m.by_final_slug
371
assert "LOCAL_ROLE_MANAGER_SET_ROLE" in m.by_final_slug
503
- assert m.by_final_slug["LOCAL_GMAIL_GET_EMAILS"].toolkit == "gmail"
372
373
374
# ────────────────────────────────────────────────────────────────
507
-# Custom tool execution tests
375
+# Execution tests
376
# ────────────────────────────────────────────────────────────────
377
378
383
result = execute_custom_tool(entry, {"pattern": "hello"}, MockSessionContext()) # type: ignore
384
assert result["successful"] is True
385
assert result["data"]["matches"] == ["hello"]
518
- assert result["data"]["path"] == "." # default value
519
- assert result["error"] is None
520
-
521
- def test_applies_pydantic_defaults(self, grep_tool):
522
- m = build_custom_tools_map([grep_tool])
523
- entry = find_custom_tool(m, "GREP")
524
- result = execute_custom_tool(entry, {"pattern": "test"}, MockSessionContext()) # type: ignore
525
- assert result["data"]["path"] == "." # default applied
386
387
def test_validation_failure(self, grep_tool):
388
m = build_custom_tools_map([grep_tool])
389
entry = find_custom_tool(m, "GREP")
530
- result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore # missing required "pattern"
390
+ result = execute_custom_tool(entry, {}, MockSessionContext()) # type: ignore
391
assert result["successful"] is False
532
- assert "validation" in result["error"].lower()
533
-
534
- def test_execute_function_error(self):
535
- def bad_execute(input, ctx):
536
- raise RuntimeError("Something went wrong")
537
-
538
- tool = experimental_create_tool(
539
- "BAD",
540
- name="Bad",
541
- description="Desc",
542
- input_params=GrepInput,
543
- execute=bad_execute,
544
- )
545
- m = build_custom_tools_map([tool])
392
+
393
+ def test_execute_error(self):
394
+ @exp.tool()
395
+ def bad(input: GrepInput, ctx):
396
+ """Bad."""
397
+ raise RuntimeError("boom")
398
+
399
+ m = build_custom_tools_map([bad])
400
entry = find_custom_tool(m, "BAD")
401
result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
402
assert result["successful"] is False
549
- assert "Something went wrong" in result["error"]
550
-
551
- def test_execute_returns_none(self):
552
- tool = experimental_create_tool(
553
- "NOOP",
554
- name="Noop",
555
- description="Returns None",
556
- input_params=GrepInput,
557
- execute=lambda i, c: None, # type: ignore
558
- )
559
- m = build_custom_tools_map([tool])
560
- entry = find_custom_tool(m, "NOOP")
561
- result = execute_custom_tool(entry, {"pattern": "x"}, MockSessionContext()) # type: ignore
562
- assert result["successful"] is True
563
- assert result["data"] == {}
403
+ assert "boom" in result["error"]
404
405
406
# ────────────────────────────────────────────────────────────────
409
410
411
class TestSessionContextImpl:
572
- def test_user_id(self):
573
- ctx = SessionContextImpl(
574
- client=MagicMock(),
575
- user_id="user-1",
576
- session_id="sess-1",
577
- )
578
- assert ctx.user_id == "user-1"
579
-
580
- def test_execute_routes_to_sibling(self, grep_tool):
412
+ def test_sibling_routing(self, grep_tool):
413
m = build_custom_tools_map([grep_tool])
414
ctx = SessionContextImpl(
583
- client=MagicMock(),
584
- user_id="user-1",
585
- session_id="sess-1",
586
- custom_tools_map=m,
415
+ client=MagicMock(), user_id="u", session_id="s", custom_tools_map=m
416
)
417
result = ctx.execute("GREP", {"pattern": "test"})
418
assert result["successful"] is True
590
- assert result["data"]["matches"] == ["test"]
419
592
- def test_execute_falls_back_to_remote(self, grep_tool):
420
+ def test_remote_fallback(self, grep_tool):
421
m = build_custom_tools_map([grep_tool])
422
mock_client = MagicMock()
595
- mock_response = MagicMock()
596
- mock_response.data = {"remote": True}
597
- mock_response.error = None
598
- mock_client.tool_router.session.execute.return_value = mock_response
599
-
423
+ mock_client.tool_router.session.execute.return_value = MagicMock(
424
+ data={"remote": True}, error=None
425
+ )
426
ctx = SessionContextImpl(
601
- client=mock_client,
602
- user_id="user-1",
603
- session_id="sess-1",
604
- custom_tools_map=m,
427
+ client=mock_client, user_id="u", session_id="s", custom_tools_map=m
428
)
606
- result = ctx.execute("NONEXISTENT_TOOL", {"arg": "val"})
429
+ ctx.execute("NONEXISTENT", {"arg": "val"})
430
mock_client.tool_router.session.execute.assert_called_once()
608
- assert result["data"] == {"remote": True}
431
432
def test_proxy_execute(self):
433
mock_client = MagicMock()
612
- mock_response = MagicMock()
613
- mock_response.status = 200
614
- mock_response.data = {"result": "ok"}
615
- mock_response.headers = {"Content-Type": "application/json"}
616
- mock_response.binary_data = None
617
- mock_client.tool_router.session.proxy_execute.return_value = mock_response
618
-
619
- ctx = SessionContextImpl(
620
- client=mock_client,
621
- user_id="user-1",
622
- session_id="sess-1",
434
+ mock_client.tool_router.session.proxy_execute.return_value = MagicMock(
435
+ status=200, data={"ok": True}, headers={}, binary_data=None
436
)
437
+ ctx = SessionContextImpl(client=mock_client, user_id="u", session_id="s")
438
result = ctx.proxy_execute(
625
- toolkit="gmail",
626
- endpoint="https://gmail.googleapis.com/test",
627
- method="GET",
439
+ toolkit="gmail", endpoint="https://example.com", method="GET"
440
)
441
assert result["status"] == 200
630
- assert result["data"] == {"result": "ok"}
631
- mock_client.tool_router.session.proxy_execute.assert_called_once()
442
443
444
# ────────────────────────────────────────────────────────────────
635
-# ToolRouterSession integration tests
445
+# ToolRouterSession integration
446
# ────────────────────────────────────────────────────────────────
447
448
449
@pytest.fixture
450
def mock_session_deps(grep_tool, email_tool, role_toolkit):
641
- """Create mock dependencies for ToolRouterSession with custom tools."""
642
- client = MagicMock()
643
- provider = MagicMock()
644
- experimental = MagicMock()
645
- experimental.files = MagicMock()
646
- experimental.assistive_prompt = None
647
-
648
- # Build tools map
649
- tools_map = build_custom_tools_map([grep_tool, email_tool], [role_toolkit])
650
-
451
return {
652
- "client": client,
653
- "provider": provider,
654
- "experimental": experimental,
655
- "tools_map": tools_map,
452
+ "client": MagicMock(),
453
+ "provider": MagicMock(),
454
+ "experimental": MagicMock(),
455
+ "tools_map": build_custom_tools_map([grep_tool, email_tool], [role_toolkit]),
456
}
457
458
459
+def _session(deps, **overrides):
460
+ kwargs = dict(
461
+ client=deps["client"],
462
+ provider=deps["provider"],
463
+ auto_upload_download_files=True,
464
+ session_id="s",
465
+ mcp=MagicMock(),
466
+ experimental=deps["experimental"],
467
+ custom_tools_map=deps["tools_map"],
468
+ user_id="u",
469
+ )
470
+ kwargs.update(overrides)
471
+ return ToolRouterSession(**kwargs)
472
+
473
+
474
class TestToolRouterSessionCustomTools:
660
- def test_execute_routes_to_local(self, mock_session_deps, grep_tool):
661
- session = ToolRouterSession(
662
- client=mock_session_deps["client"],
663
- provider=mock_session_deps["provider"],
664
- auto_upload_download_files=True,
665
- session_id="sess-1",
666
- mcp=MagicMock(),
667
- experimental=mock_session_deps["experimental"],
668
- custom_tools_map=mock_session_deps["tools_map"],
669
- user_id="user-1",
670
- )
671
- result = session.execute("GREP", arguments={"pattern": "test"})
672
- # session.execute returns SessionExecuteResponse shape: data, error, log_id
673
- assert result["data"]["matches"] == ["test"]
475
+ def test_execute_local(self, mock_session_deps):
476
+ s = _session(mock_session_deps)
477
+ result = s.execute("GREP", arguments={"pattern": "x"})
478
assert result["error"] is None
479
assert result["log_id"] == ""
676
- # Should NOT have called the backend
480
mock_session_deps["client"].tool_router.session.execute.assert_not_called()
481
679
- def test_execute_routes_to_local_by_final_slug(self, mock_session_deps):
680
- session = ToolRouterSession(
681
- client=mock_session_deps["client"],
682
- provider=mock_session_deps["provider"],
683
- auto_upload_download_files=True,
684
- session_id="sess-1",
685
- mcp=MagicMock(),
686
- experimental=mock_session_deps["experimental"],
687
- custom_tools_map=mock_session_deps["tools_map"],
688
- user_id="user-1",
689
- )
690
- result = session.execute("LOCAL_GREP", arguments={"pattern": "test"})
691
- assert result["error"] is None
692
-
693
- def test_execute_case_insensitive(self, mock_session_deps):
694
- session = ToolRouterSession(
695
- client=mock_session_deps["client"],
696
- provider=mock_session_deps["provider"],
697
- auto_upload_download_files=True,
698
- session_id="sess-1",
699
- mcp=MagicMock(),
700
- experimental=mock_session_deps["experimental"],
701
- custom_tools_map=mock_session_deps["tools_map"],
702
- user_id="user-1",
703
- )
704
- result = session.execute("grep", arguments={"pattern": "test"})
705
- assert result["error"] is None
706
-
707
- def test_execute_routes_to_remote(self, mock_session_deps):
708
- mock_response = MagicMock()
482
+ def test_execute_remote(self, mock_session_deps):
483
mock_session_deps[
484
"client"
711
- ].tool_router.session.execute.return_value = mock_response
712
-
713
- session = ToolRouterSession(
714
- client=mock_session_deps["client"],
715
- provider=mock_session_deps["provider"],
716
- auto_upload_download_files=True,
717
- session_id="sess-1",
718
- mcp=MagicMock(),
719
- experimental=mock_session_deps["experimental"],
720
- custom_tools_map=mock_session_deps["tools_map"],
721
- user_id="user-1",
722
- )
723
- session.execute("GMAIL_SEND_EMAIL", arguments={"to": "alice@example.com"})
485
+ ].tool_router.session.execute.return_value = MagicMock()
486
+ s = _session(mock_session_deps)
487
+ s.execute("GMAIL_SEND_EMAIL", arguments={"to": "a@b.com"})
488
mock_session_deps["client"].tool_router.session.execute.assert_called_once()
489
490
def test_custom_tools_list(self, mock_session_deps):
727
- session = ToolRouterSession(
728
- client=mock_session_deps["client"],
729
- provider=mock_session_deps["provider"],
730
- auto_upload_download_files=True,
731
- session_id="sess-1",
732
- mcp=MagicMock(),
733
- experimental=mock_session_deps["experimental"],
734
- custom_tools_map=mock_session_deps["tools_map"],
735
- user_id="user-1",
736
- )
737
- tools = session.custom_tools()
738
- assert len(tools) == 3
739
- slugs = {t.slug for t in tools}
740
- assert "LOCAL_GREP" in slugs
741
- assert "LOCAL_GMAIL_GET_EMAILS" in slugs
742
- assert "LOCAL_ROLE_MANAGER_SET_ROLE" in slugs
743
-
744
- def test_custom_tools_filter_by_toolkit(self, mock_session_deps):
745
- session = ToolRouterSession(
746
- client=mock_session_deps["client"],
747
- provider=mock_session_deps["provider"],
748
- auto_upload_download_files=True,
749
- session_id="sess-1",
750
- mcp=MagicMock(),
751
- experimental=mock_session_deps["experimental"],
752
- custom_tools_map=mock_session_deps["tools_map"],
753
- user_id="user-1",
754
- )
755
- gmail_tools = session.custom_tools(toolkit="gmail")
756
- assert len(gmail_tools) == 1
757
- assert gmail_tools[0].slug == "LOCAL_GMAIL_GET_EMAILS"
491
+ s = _session(mock_session_deps)
492
+ assert len(s.custom_tools()) == 3
493
+
494
+ def test_custom_tools_filter(self, mock_session_deps):
495
+ s = _session(mock_session_deps)
496
+ assert len(s.custom_tools(toolkit="gmail")) == 1
497
498
def test_custom_toolkits_list(self, mock_session_deps):
760
- session = ToolRouterSession(
761
- client=mock_session_deps["client"],
762
- provider=mock_session_deps["provider"],
763
- auto_upload_download_files=True,
764
- session_id="sess-1",
765
- mcp=MagicMock(),
766
- experimental=mock_session_deps["experimental"],
767
- custom_tools_map=mock_session_deps["tools_map"],
768
- user_id="user-1",
769
- )
770
- toolkits = session.custom_toolkits()
771
- assert len(toolkits) == 1
772
- assert toolkits[0].slug == "ROLE_MANAGER"
773
- assert len(toolkits[0].tools) == 1
774
- assert toolkits[0].tools[0].slug == "LOCAL_ROLE_MANAGER_SET_ROLE"
775
-
776
- def test_custom_tools_empty_when_no_map(self):
777
- session = ToolRouterSession(
499
+ s = _session(mock_session_deps)
500
+ tks = s.custom_toolkits()
501
+ assert len(tks) == 1
502
+ assert tks[0].slug == "ROLE_MANAGER"
503
+
504
+ def test_empty_when_no_map(self):
505
+ s = ToolRouterSession(
506
client=MagicMock(),
507
provider=MagicMock(),
508
auto_upload_download_files=True,
781
- session_id="sess-1",
509
+ session_id="s",
510
mcp=MagicMock(),
511
experimental=MagicMock(),
512
)
785
- assert session.custom_tools() == []
786
- assert session.custom_toolkits() == []
787
-
788
- def test_proxy_execute(self, mock_session_deps):
789
- mock_response = MagicMock()
790
- mock_response.status = 200
791
- mock_response.data = {"result": "ok"}
792
- mock_response.headers = {"Content-Type": "application/json"}
793
- mock_response.binary_data = None
794
- mock_session_deps[
795
- "client"
796
- ].tool_router.session.proxy_execute.return_value = mock_response
797
-
798
- session = ToolRouterSession(
799
- client=mock_session_deps["client"],
800
- provider=mock_session_deps["provider"],
801
- auto_upload_download_files=True,
802
- session_id="sess-1",
803
- mcp=MagicMock(),
804
- experimental=mock_session_deps["experimental"],
805
- )
806
- result = session.proxy_execute(
807
- toolkit="gmail",
808
- endpoint="https://gmail.googleapis.com/test",
809
- method="GET",
810
- )
811
- assert result["status"] == 200
812
- mock_session_deps[
813
- "client"
814
- ].tool_router.session.proxy_execute.assert_called_once()
513
+ assert s.custom_tools() == []
514
515
516
# ────────────────────────────────────────────────────────────────
818
-# Multi-execute routing tests
517
+# Multi-execute routing
518
# ────────────────────────────────────────────────────────────────
519
520
521
class TestMultiExecuteRouting:
823
- def _make_session(self, grep_tool, mock_client=None):
824
- m = build_custom_tools_map([grep_tool])
825
- client = mock_client or MagicMock()
826
- session = ToolRouterSession(
827
- client=client,
522
+ def _make_session(self, *tools):
523
+ m = build_custom_tools_map(list(tools))
524
+ return ToolRouterSession(
525
+ client=MagicMock(),
526
provider=MagicMock(),
527
auto_upload_download_files=True,
830
- session_id="sess-1",
528
+ session_id="s",
529
mcp=MagicMock(),
530
experimental=MagicMock(),
531
custom_tools_map=m,
834
- user_id="user-1",
532
+ user_id="u",
533
)
836
- return session
837
-
838
- def test_route_all_local(self, grep_tool):
839
- session = self._make_session(grep_tool)
840
- mock_tools_model = MagicMock()
534
842
- result = session._route_multi_execute(
843
- {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "test"}}]},
844
- mock_tools_model,
535
+ def test_single_local(self, grep_tool):
536
+ s = self._make_session(grep_tool)
537
+ result = s._route_multi_execute(
538
+ {"tools": [{"tool_slug": "GREP", "arguments": {"pattern": "x"}}]},
539
+ MagicMock(),
540
None,
541
)
847
- # Single local tool returns unwrapped
542
assert result["successful"] is True
849
- assert result["data"]["matches"] == ["test"]
850
-
851
- def test_route_all_remote(self, grep_tool):
852
- session = self._make_session(grep_tool)
853
- mock_tools_model = MagicMock()
854
-
855
- remote_response = {
543
+ assert result["data"]["matches"] == ["x"]
544
+
545
+ def test_all_remote(self, grep_tool):
546
+ s = self._make_session(grep_tool)
547
+ tm = MagicMock()
548
+ remote = {"data": {"results": []}, "error": None, "successful": True}
549
+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
550
+ result = s._route_multi_execute(
551
+ {"tools": [{"tool_slug": "REMOTE", "arguments": {}}]}, tm, None
552
+ )
553
+ assert result == remote
554
+
555
+ def test_mixed(self, grep_tool):
556
+ s = self._make_session(grep_tool)
557
+ tm = MagicMock()
558
+ remote = {
559
"data": {
560
"results": [
858
- {"tool_slug": "GMAIL_SEND", "response": {"successful": True}}
561
+ {"tool_slug": "R", "response": {"successful": True, "data": {}}}
562
]
563
},
564
"error": None,
565
"successful": True,
566
}
864
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
865
- lambda slug, args: remote_response
866
- )
867
-
868
- result = session._route_multi_execute(
567
+ tm._wrap_execute_tool_for_tool_router.return_value = lambda slug, args: remote
568
+ result = s._route_multi_execute(
569
{
570
"tools": [
871
- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "alice@x.com"}}
571
+ {"tool_slug": "GREP", "arguments": {"pattern": "x"}},
572
+ {"tool_slug": "REMOTE", "arguments": {}},
573
]
574
},
874
- mock_tools_model,
575
+ tm,
576
None,
577
)
877
- assert result == remote_response
578
+ assert len(result["data"]["results"]) == 2
579
879
- def test_route_mixed_local_and_remote(self, grep_tool):
880
- session = self._make_session(grep_tool)
881
- mock_tools_model = MagicMock()
580
+ def test_failure_propagated(self):
581
+ @exp.tool()
582
+ def ok_tool(input: GrepInput, ctx):
583
+ """OK."""
584
+ return {"ok": True}
585
883
- remote_response = {
884
- "data": {
885
- "results": [
886
- {
887
- "tool_slug": "GMAIL_SEND",
888
- "response": {"successful": True, "data": {"sent": True}},
889
- }
890
- ]
891
- },
892
- "error": None,
893
- "successful": True,
894
- }
895
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
896
- lambda slug, args: remote_response
897
- )
586
+ @exp.tool()
587
+ def bad_tool(input: GrepInput, ctx):
588
+ """Bad."""
589
+ raise RuntimeError("boom")
590
899
- result = session._route_multi_execute(
900
- {
901
- "tools": [
902
- {"tool_slug": "GREP", "arguments": {"pattern": "test"}},
903
- {"tool_slug": "GMAIL_SEND", "arguments": {"to": "alice@x.com"}},
904
- ]
905
- },
906
- mock_tools_model,
907
- None,
908
- )
909
- # Should have merged results
910
- assert result["successful"] is True
911
- results = result["data"]["results"]
912
- assert len(results) == 2
913
- # First should be the local GREP result
914
- assert results[0]["tool_slug"] == "GREP"
915
- assert results[0]["response"]["successful"] is True
916
- # Second should be the remote result
917
- assert results[1]["tool_slug"] == "GMAIL_SEND"
918
-
919
- def test_route_empty_tools(self, grep_tool):
920
- session = self._make_session(grep_tool)
921
- mock_tools_model = MagicMock()
922
- fallback_result = {"data": {}, "error": None, "successful": True}
923
- mock_tools_model._wrap_execute_tool_for_tool_router.return_value = (
924
- lambda slug, args: fallback_result
925
- )
926
-
927
- result = session._route_multi_execute({"tools": []}, mock_tools_model, None)
928
- # Should fall back to remote
929
- assert result == fallback_result
930
-
931
- def test_route_multiple_local_tools(self):
932
- tool1 = experimental_create_tool(
933
- "TOOL_A",
934
- name="A",
935
- description="D",
936
- input_params=GrepInput,
937
- execute=lambda i, c: {"tool": "A", "pattern": i.pattern},
938
- )
939
- tool2 = experimental_create_tool(
940
- "TOOL_B",
941
- name="B",
942
- description="D",
943
- input_params=GrepInput,
944
- execute=lambda i, c: {"tool": "B", "pattern": i.pattern},
945
- )
946
- m = build_custom_tools_map([tool1, tool2])
947
- session = ToolRouterSession(
948
- client=MagicMock(),
949
- provider=MagicMock(),
950
- auto_upload_download_files=True,
951
- session_id="sess-1",
952
- mcp=MagicMock(),
953
- experimental=MagicMock(),
954
- custom_tools_map=m,
955
- user_id="user-1",
956
- )
957
- result = session._route_multi_execute(
958
- {
959
- "tools": [
960
- {"tool_slug": "TOOL_A", "arguments": {"pattern": "x"}},
961
- {"tool_slug": "TOOL_B", "arguments": {"pattern": "y"}},
962
- ]
963
- },
964
- MagicMock(),
965
- None,
966
- )
967
- assert result["successful"] is True
968
- results = result["data"]["results"]
969
- assert len(results) == 2
970
- assert results[0]["response"]["data"]["tool"] == "A"
971
- assert results[1]["response"]["data"]["tool"] == "B"
972
-
973
- def test_route_propagates_local_failure(self):
974
- ok_tool = experimental_create_tool(
975
- "OK",
976
- name="OK",
977
- description="D",
978
- input_params=GrepInput,
979
- execute=lambda i, c: {"ok": True},
980
- )
981
- bad_tool = experimental_create_tool(
982
- "BAD",
983
- name="Bad",
984
- description="D",
985
- input_params=GrepInput,
986
- execute=lambda i, c: (_ for _ in ()).throw(RuntimeError("boom")),
987
- )
988
- m = build_custom_tools_map([ok_tool, bad_tool])
989
- session = ToolRouterSession(
990
- client=MagicMock(),
991
- provider=MagicMock(),
992
- auto_upload_download_files=True,
993
- session_id="sess-1",
994
- mcp=MagicMock(),
995
- experimental=MagicMock(),
996
- custom_tools_map=m,
997
- user_id="user-1",
998
- )
999
- result = session._route_multi_execute(
591
+ s = self._make_session(ok_tool, bad_tool)
592
+ result = s._route_multi_execute(
593
{
594
"tools": [
1002
- {"tool_slug": "OK", "arguments": {"pattern": "x"}},
1003
- {"tool_slug": "BAD", "arguments": {"pattern": "y"}},
595
+ {"tool_slug": "OK_TOOL", "arguments": {"pattern": "x"}},
596
+ {"tool_slug": "BAD_TOOL", "arguments": {"pattern": "y"}},
597
]
598
},
599
MagicMock(),
600
None,
601
)
1009
- # Overall result should report failure
602
assert result["successful"] is False
603
assert "1 out of 2" in result["error"]
1012
- # Individual results preserved
1013
- results = result["data"]["results"]
1014
- assert results[0]["response"]["successful"] is True
1015
- assert results[1]["response"]["successful"] is False