Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Fix Throw error when explicit toolkit version is not provided for manual execute (#2070)
Musthaq Ahamad committed
Oct 22, 2025 at 11:01 UTC
157bf7ba4ece92af8fc02ada5a45ae980da33828
36 files changed
+1353
-130
.changeset/vast-rings-tan.md
new
+68
@@ -0,0 +1,68 @@
1
+---
2
+'@composio/core': minor
3
+'@composio/anthropic': minor
4
+'@composio/cloudflare': minor
5
+'@composio/google': minor
6
+'@composio/langchain': minor
7
+'@composio/llamaindex': minor
8
+'@composio/mastra': minor
9
+'@composio/openai': minor
10
+'@composio/openai-agents': minor
11
+'@composio/vercel': patch
12
+'@composio/json-schema-to-zod': patch
13
+---
14
+
15
+### Added
16
+- **Version validation for manual tool execution**: Tools now require explicit toolkit version specification when executing manually to prevent unexpected behavior from `latest` version changes
17
+- **New `dangerously_skip_version_check` parameter** (Python) / `dangerouslySkipVersionCheck` (TypeScript): Optional flag to bypass version validation (use with caution)
18
+- **`ToolVersionRequiredError` exception** (Python): Raised when attempting to execute tools with `latest` version without skip flag, includes helpful error messages with 4 possible fixes
19
+- **`ComposioToolVersionRequiredError` error** (TypeScript): Parallel implementation for TypeScript SDK with detailed error context and resolution suggestions
20
+- **Comprehensive test coverage**: Added 19 new test methods in Python covering all tool execution scenarios including version resolution, error handling, modifiers, and environment variables
21
+
22
+### Changed
23
+- **Tool execution behavior**: Manual execution via `tools.execute()` now validates toolkit versions before API calls
24
+- **Agentic provider flows**: Automatically set `dangerously_skip_version_check=True` internally to maintain backward compatibility for framework integrations
25
+- **Instance-level version resolution**: Both `execute()` and `_execute_tool()` methods now consistently resolve versions from instance-level `toolkit_versions` configuration
26
+- **Modifier support**: Added `dangerously_skip_version_check` to modifier parameter types for complete flow coverage
27
+- **Test version format**: Updated all test files to use production date-based version format (`20251201_XX`) instead of semantic versioning
28
+
29
+### Fixed
30
+- **Consistent version handling**: Removed `toolkit_versions` parameter from `_execute_tool()` in favor of instance-level configuration, ensuring consistent version resolution across the SDK
31
+- **Code formatting**: Applied ruff formatting to all modified Python files
32
+- **Array parsing to ZodSchema**: Fixes in json-schema-to-zod to parse array without properties and with properties
33
+
34
+### Migration Guide
35
+When manually executing tools, you must now specify toolkit versions:
36
+
37
+**Option 1: Pass explicit version parameter**
38
+```python
39
+tools.execute("GITHUB_CREATE_ISSUE",
40
+ arguments={...},
41
+ version="20251201_01"
42
+)
43
+```
44
+
45
+**Option 2: Configure at SDK initialization**
46
+```python
47
+tools = Tools(client, provider,
48
+ toolkit_versions={"github": "20251201_01"}
49
+)
50
+```
51
+
52
+**Option 3: Use environment variables**
53
+```bash
54
+export COMPOSIO_TOOLKIT_VERSION_GITHUB=20251201_01
55
+```
56
+
57
+**Option 4: Skip validation (not recommended)**
58
+```python
59
+tools.execute("GITHUB_CREATE_ISSUE",
60
+ arguments={...},
61
+ dangerously_skip_version_check=True
62
+)
63
+```
64
+
65
+### Developer Notes
66
+- Agentic framework integrations (LangChain, CrewAI, etc.) are not affected as they automatically use the skip flag
67
+- The `latest` version can still be used with the skip flag, but specific versions are strongly recommended
68
+- Error messages include all available resolution options for better developer experience
\ No newline at end of file
python/composio/core/models/_modifiers.py
+1
@@ -18,6 +18,7 @@ class ToolExecuteParams(te.TypedDict):
18
user_id: t.Optional[str]
19
text: t.Optional[str]
20
version: t.Optional[str]
21
+ dangerously_skip_version_check: te.NotRequired[t.Optional[bool]]
22
23
24
ModifierInOut = t.Union["ToolExecuteParams", "ToolExecutionResponse", "Tool"]
python/composio/core/models/tools.py
+24
-14
@@ -25,7 +25,7 @@ from composio.core.provider.none_agentic import (
25
NoneAgenticProviderExecuteFn,
26
)
27
from composio.core.types import ToolkitVersionParam
28
-from composio.exceptions import InvalidParams, NotFoundError
28
+from composio.exceptions import InvalidParams, NotFoundError, ToolVersionRequiredError
29
from composio.utils.pydantic import none_to_omit
30
from composio.utils.toolkit_version import get_toolkit_version
31
@@ -296,6 +296,9 @@ class Tools(Resource, t.Generic[TProvider]):
296
self.execute,
297
modifiers=modifiers,
298
user_id=user_id,
299
+ # Dangerously skip version check for agentic and non-agentic tool execution via providers
300
+ # This can be safe because most agentic flows users fetch latest version and then execute the tool
301
+ dangerously_skip_version_check=True,
302
),
303
)
304
@@ -336,17 +339,23 @@ class Tools(Resource, t.Generic[TProvider]):
339
user_id: t.Optional[str] = None,
340
text: t.Optional[str] = None,
341
version: t.Optional[str] = None,
339
- toolkit_versions: t.Optional[ToolkitVersionParam] = None,
342
+ dangerously_skip_version_check: t.Optional[bool] = None,
343
) -> ToolExecutionResponse:
344
"""Execute a tool"""
345
# Get the tool to determine its toolkit
346
tool = self.get_raw_composio_tool_by_slug(slug)
347
345
- # If version is not explicitly provided, resolve it from toolkit versions
346
- # This matches the TypeScript behavior
347
- if version is None and toolkit_versions is not None:
348
+ # If version is not explicitly provided, resolve it from instance-level toolkit versions
349
+ # This matches the TypeScript behavior - always resolve version when None
350
+ if version is None:
351
toolkit_slug = tool.toolkit.slug if tool.toolkit else "unknown"
349
- version = get_toolkit_version(toolkit_slug, toolkit_versions)
352
+ # Use instance-level toolkit versions configuration
353
+ version = get_toolkit_version(toolkit_slug, self._toolkit_versions)
354
+
355
+ # Check if the version is 'latest' and dangerously_skip_version_check is not True
356
+ # If so, raise an error to prevent unexpected behavior
357
+ if version == "latest" and not dangerously_skip_version_check:
358
+ raise ToolVersionRequiredError()
359
360
return t.cast(
361
ToolExecutionResponse,
@@ -359,7 +368,6 @@ class Tools(Resource, t.Generic[TProvider]):
368
user_id=none_to_omit(user_id),
369
text=none_to_omit(text),
370
version=none_to_omit(version),
362
- # Note: We don't pass toolkit_versions to the API, we resolve the specific version above
371
).model_dump(
372
exclude={
373
"log_id",
@@ -381,7 +389,7 @@ class Tools(Resource, t.Generic[TProvider]):
389
user_id: t.Optional[str] = None,
390
text: t.Optional[str] = None,
391
version: t.Optional[str] = None,
384
- toolkit_versions: t.Optional[ToolkitVersionParam] = None,
392
+ dangerously_skip_version_check: t.Optional[bool] = None,
393
modifiers: t.Optional[Modifiers] = None,
394
) -> ToolExecutionResponse:
395
"""
@@ -398,13 +406,11 @@ class Tools(Resource, t.Generic[TProvider]):
406
:param custom_connection_data: The custom connection data to use for the tool, takes priority over custom_auth_params.
407
:param user_id: The ID of the user to execute the tool for.
408
:param text: The text to pass to the tool.
401
- :param version: The version of the tool to execute.
402
- :param toolkit_versions: Toolkit versions to use for execution, overrides the SDK-level configuration.
409
+ :param version: The version of the tool to execute (overrides the SDK-level toolkit versions for this execution).
410
+ :param dangerously_skip_version_check: Skip the version check for 'latest' version. This might cause unexpected behavior when new versions are released.
411
:param modifiers: The modifiers to apply to the tool.
412
:return: The response from the tool.
413
"""
406
- # Use provided toolkit_versions or fall back to instance-level versions
407
- effective_toolkit_versions = toolkit_versions or self._toolkit_versions
414
415
tool = self._tool_schemas.get(slug)
416
if tool is None and self._custom_tools.get(slug=slug) is not None:
@@ -416,7 +422,7 @@ class Tools(Resource, t.Generic[TProvider]):
422
Tool,
423
self._client.tools.retrieve(
424
tool_slug=slug,
419
- toolkit_versions=none_to_omit(effective_toolkit_versions),
425
+ toolkit_versions=none_to_omit(self._toolkit_versions),
426
),
427
)
428
self._tool_schemas[slug] = tool
@@ -435,6 +441,7 @@ class Tools(Resource, t.Generic[TProvider]):
441
"text": text,
442
"user_id": user_id,
443
"arguments": arguments,
444
+ "dangerously_skip_version_check": dangerously_skip_version_check,
445
},
446
)
447
connected_account_id = processed_params["connected_account_id"]
@@ -444,6 +451,9 @@ class Tools(Resource, t.Generic[TProvider]):
451
version = processed_params["version"]
452
user_id = processed_params["user_id"]
453
arguments = processed_params["arguments"]
454
+ dangerously_skip_version_check = processed_params.get(
455
+ "dangerously_skip_version_check"
456
+ )
457
458
arguments = self._file_helper.substitute_file_uploads(
459
tool=tool,
@@ -465,7 +475,7 @@ class Tools(Resource, t.Generic[TProvider]):
475
user_id=user_id,
476
text=text,
477
version=version,
468
- toolkit_versions=none_to_omit(effective_toolkit_versions),
478
+ dangerously_skip_version_check=dangerously_skip_version_check,
479
)
480
)
481
response = self._file_helper.substitute_file_downloads(
python/composio/exceptions.py
+21
@@ -281,5 +281,26 @@ class ExecuteToolFnNotSetError(ComposioError):
281
pass
282
283
284
+class ToolVersionRequiredError(ComposioError):
285
+ """Raised when toolkit version is not specified for manual tool execution."""
286
+
287
+ def __init__(self) -> None:
288
+ super().__init__(
289
+ message=(
290
+ "Toolkit version not specified. For manual execution of the tool "
291
+ "please pass a specific toolkit version.\n\n"
292
+ "Possible fixes:\n"
293
+ "1. Pass the toolkit version as a parameter to the execute function "
294
+ '("latest" is not supported in manual execution)\n'
295
+ "2. Set the toolkit versions in the Composio config "
296
+ "(toolkit_versions={'<toolkit-slug>': '<toolkit-version>'})\n"
297
+ "3. Set the toolkit version in the environment variable "
298
+ "(COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>)\n"
299
+ "4. Set dangerously_skip_version_check to True "
300
+ "(this might cause unexpected behavior when new versions of the tools are released)"
301
+ ),
302
+ )
303
+
304
+
305
class UsageError(ComposioError):
306
pass
python/providers/anthropic/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-anthropic"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your Anthropic LLMs."
5
readme = "README.md"
6
requires-python = ">=3.10,<4"
python/providers/anthropic/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_anthropic",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Anthropic LLMs.",
python/providers/autogen/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-autogen"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your autogen agent."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/autogen/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_autogen",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Autogen agent.",
python/providers/crewai/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-crewai"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your CrewAI agent."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/crewai/setup.py
+1
-1
@@ -6,7 +6,7 @@ from setuptools import setup
6
7
setup(
8
name="composio_crewai",
9
- version="0.8.20",
9
+ version="0.9.0",
10
author="Composio",
11
author_email="tech@composio.dev",
12
description="Use Composio to get an array of tools with your CrewAI agent.",
python/providers/gemini/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-gemini"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your Gemini agent."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/gemini/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_gemini",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Gemini agent.",
python/providers/google/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-google"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/google/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_google",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
python/providers/google_adk/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-google-adk"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your Google AI Python Gemini model."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/google_adk/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_google_adk",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Google AI Python Gemini model.",
python/providers/langchain/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-langchain"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your Langchain agent."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/langchain/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_langchain",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your Langchain agent.",
python/providers/langgraph/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-langgraph"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get array of tools with LangGraph Agent Workflows."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/langgraph/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_langgraph",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get array of tools with LangGraph Agent Workflows",
python/providers/llamaindex/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-llamaindex"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get array of tools with LlamaIndex Agent Workflows."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/llamaindex/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_llamaindex",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get array of tools with LlamaIndex Agent Workflows",
python/providers/openai/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-openai"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get an array of tools with your OpenAI Function Call."
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/openai/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import setup
8
9
setup(
10
name="composio_openai",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get an array of tools with your OpenAI Function Call.",
python/providers/openai_agents/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio-openai-agents"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "Use Composio to get array of strongly typed tools for OpenAI Agents"
5
readme = "README.md"
6
requires-python = ">=3.9,<4"
python/providers/openai_agents/setup.py
+1
-1
@@ -8,7 +8,7 @@ from setuptools import find_packages, setup
8
9
setup(
10
name="composio_openai_agents",
11
- version="0.8.20",
11
+ version="0.9.0",
12
author="Composio",
13
author_email="tech@composio.dev",
14
description="Use Composio to get array of strongly typed tools for OpenAI Agents",
python/pyproject.toml
+1
-1
@@ -1,6 +1,6 @@
1
[project]
2
name = "composio"
3
-version = "0.8.20"
3
+version = "0.9.0"
4
description = "SDK for integrating Composio with your applications."
5
readme = "README.md"
6
requires-python = ">=3.10,<4"
python/tests/test_tool_execution.py
+716
-26
@@ -1,9 +1,20 @@
1
"""Test tool execution with toolkit versions."""
2
3
+import pytest
4
from unittest.mock import Mock, patch
5
6
from composio.client.types import Tool, tool_list_response
7
from composio.core.models.tools import Tools
8
+from composio.core.models.base import allow_tracking
9
+from composio.exceptions import ToolVersionRequiredError
10
+
11
+
12
+@pytest.fixture(autouse=True)
13
+def disable_telemetry():
14
+ """Disable telemetry for all tests to prevent thread issues."""
15
+ token = allow_tracking.set(False)
16
+ yield
17
+ allow_tracking.reset(token)
18
19
20
class TestToolExecution:
@@ -42,7 +53,7 @@ class TestToolExecution:
53
mock_provider.name = "test_provider"
54
55
# Create toolkit versions configuration
45
- toolkit_versions = {"github": "v2.0.0", "slack": "v1.5.0"}
56
+ toolkit_versions = {"github": "20251201_01", "slack": "20251201_02"}
57
58
# Create Tools instance
59
tools = Tools(
@@ -71,15 +82,14 @@ class TestToolExecution:
82
tools._execute_tool(
83
slug="GITHUB_GET_REPOS",
84
arguments={"owner": "test", "repo": "test"},
74
- toolkit_versions=toolkit_versions,
85
)
86
87
# Verify that the client was called with the resolved version
88
mock_client.tools.execute.assert_called_once()
89
call_args = mock_client.tools.execute.call_args
90
81
- # Should have called with version="v2.0.0" (resolved from github toolkit)
82
- assert call_args.kwargs["version"] == "v2.0.0"
91
+ # Should have called with version="20251201_01" (resolved from github toolkit)
92
+ assert call_args.kwargs["version"] == "20251201_01"
93
94
def test_tool_execution_with_explicit_version(self):
95
"""Test that explicit version overrides toolkit version."""
@@ -90,7 +100,7 @@ class TestToolExecution:
100
101
# Create toolkit versions configuration
102
toolkit_versions = {
93
- "github": "v2.0.0",
103
+ "github": "20251201_01",
104
}
105
106
# Create Tools instance
@@ -120,8 +130,7 @@ class TestToolExecution:
130
tools._execute_tool(
131
slug="GITHUB_GET_REPOS",
132
arguments={"owner": "test", "repo": "test"},
123
- version="v3.0.0", # Explicit version should take precedence
124
- toolkit_versions=toolkit_versions,
133
+ version="20251201_03", # Explicit version should take precedence
134
)
135
136
# Verify that the client was called with the explicit version
@@ -129,7 +138,7 @@ class TestToolExecution:
138
call_args = mock_client.tools.execute.call_args
139
140
# Should have called with explicit version, not resolved from toolkit
132
- assert call_args.kwargs["version"] == "v3.0.0"
141
+ assert call_args.kwargs["version"] == "20251201_03"
142
143
def test_tool_execution_unknown_toolkit_fallback(self):
144
"""Test that unknown toolkit falls back to 'latest'."""
@@ -140,7 +149,7 @@ class TestToolExecution:
149
150
# Create toolkit versions configuration that doesn't include the tool's toolkit
151
toolkit_versions = {
143
- "slack": "v1.5.0" # No github version specified
152
+ "slack": "20251201_02" # No github version specified
153
}
154
155
# Create Tools instance
@@ -166,11 +175,11 @@ class TestToolExecution:
175
}
176
mock_client.tools.execute.return_value = mock_execute_response
177
169
- # Execute the tool
178
+ # Execute the tool with dangerously_skip_version_check since version will be 'latest'
179
tools._execute_tool(
180
slug="GITHUB_GET_REPOS",
181
arguments={"owner": "test", "repo": "test"},
173
- toolkit_versions=toolkit_versions,
182
+ dangerously_skip_version_check=True,
183
)
184
185
# Verify that the client was called with "latest" (fallback)
@@ -188,7 +197,7 @@ class TestToolExecution:
197
mock_provider.name = "test_provider"
198
199
# Create global toolkit version (string)
191
- toolkit_versions = "v3.0.0"
200
+ toolkit_versions = "20251201_03"
201
202
# Create Tools instance
203
tools = Tools(
@@ -217,7 +226,6 @@ class TestToolExecution:
226
tools._execute_tool(
227
slug="GITHUB_GET_REPOS",
228
arguments={"owner": "test", "repo": "test"},
220
- toolkit_versions=toolkit_versions,
229
)
230
231
# Verify that the client was called with the global version
@@ -225,7 +233,7 @@ class TestToolExecution:
233
call_args = mock_client.tools.execute.call_args
234
235
# Should have called with the global version string
228
- assert call_args.kwargs["version"] == "v3.0.0"
236
+ assert call_args.kwargs["version"] == "20251201_03"
237
238
def test_tool_execution_matches_typescript_behavior(self):
239
"""Test that Python execution matches TypeScript behavior exactly."""
@@ -239,9 +247,9 @@ class TestToolExecution:
247
248
# Create toolkit versions like TypeScript would have
249
toolkit_versions = {
242
- "github": "20250906_01",
250
+ "github": "20251201_01",
251
"slack": "latest",
244
- "notion": "20250901_05",
252
+ "notion": "20251201_05",
253
}
254
255
# Create Tools instance
@@ -253,13 +261,23 @@ class TestToolExecution:
261
262
# Test cases matching TypeScript behavior
263
test_cases = [
256
- ("GITHUB_GET_REPOS", "github", "20250906_01"),
257
- ("SLACK_SEND_MESSAGE", "slack", "latest"),
258
- ("NOTION_CREATE_PAGE", "notion", "20250901_05"),
259
- ("CUSTOM_TOOL", "unknown_toolkit", "latest"), # Unknown toolkit fallback
264
+ ("GITHUB_GET_REPOS", "github", "20251201_01", False),
265
+ (
266
+ "SLACK_SEND_MESSAGE",
267
+ "slack",
268
+ "latest",
269
+ True,
270
+ ), # Need skip flag for latest
271
+ ("NOTION_CREATE_PAGE", "notion", "20251201_05", False),
272
+ (
273
+ "CUSTOM_TOOL",
274
+ "unknown_toolkit",
275
+ "latest",
276
+ True,
277
+ ), # Unknown toolkit fallback to latest
278
]
279
262
- for tool_slug, toolkit_slug, expected_version in test_cases:
280
+ for tool_slug, toolkit_slug, expected_version, needs_skip in test_cases:
281
# Create mock tool
282
mock_tool = self.create_mock_tool(tool_slug, toolkit_slug)
283
@@ -277,11 +295,17 @@ class TestToolExecution:
295
mock_client.tools.execute.return_value = mock_execute_response
296
297
# Execute the tool
280
- tools._execute_tool(
281
- slug=tool_slug,
282
- arguments={"test": "data"},
283
- toolkit_versions=toolkit_versions,
284
- )
298
+ if needs_skip:
299
+ tools._execute_tool(
300
+ slug=tool_slug,
301
+ arguments={"test": "data"},
302
+ dangerously_skip_version_check=True,
303
+ )
304
+ else:
305
+ tools._execute_tool(
306
+ slug=tool_slug,
307
+ arguments={"test": "data"},
308
+ )
309
310
# Verify the version matches expected
311
call_args = mock_client.tools.execute.call_args
@@ -291,3 +315,669 @@ class TestToolExecution:
315
316
# Reset mock for next iteration
317
mock_client.tools.execute.reset_mock()
318
+
319
+ def test_execute_raises_error_when_version_is_latest_without_skip_flag(self):
320
+ """Test that execute raises ToolVersionRequiredError when version is 'latest' without skip flag."""
321
+ # Mock client and provider
322
+ mock_client = Mock()
323
+ mock_provider = Mock()
324
+ mock_provider.name = "test_provider"
325
+
326
+ # Create Tools instance without toolkit versions (defaults to latest)
327
+ tools = Tools(
328
+ client=mock_client,
329
+ provider=mock_provider,
330
+ )
331
+
332
+ # Create a mock GitHub tool with proper input_parameters for file helper
333
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
334
+ github_tool.input_parameters = {"type": "object", "properties": {}}
335
+
336
+ # Mock the retrieve method
337
+ mock_client.tools.retrieve.return_value = github_tool
338
+
339
+ # Execute should raise ToolVersionRequiredError since version will be 'latest'
340
+ with pytest.raises(ToolVersionRequiredError) as exc_info:
341
+ tools.execute(
342
+ slug="GITHUB_GET_REPOS",
343
+ arguments={"owner": "test", "repo": "test"},
344
+ )
345
+
346
+ assert "Toolkit version not specified" in str(exc_info.value)
347
+
348
+ def test_execute_allows_latest_with_dangerously_skip_version_check(self):
349
+ """Test that execute allows 'latest' version when dangerously_skip_version_check is True."""
350
+ # Mock client and provider
351
+ mock_client = Mock()
352
+ mock_provider = Mock()
353
+ mock_provider.name = "test_provider"
354
+
355
+ # Create Tools instance without toolkit versions (defaults to latest)
356
+ tools = Tools(
357
+ client=mock_client,
358
+ provider=mock_provider,
359
+ )
360
+
361
+ # Create a mock GitHub tool
362
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
363
+
364
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
365
+ with patch.object(
366
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
367
+ ):
368
+ mock_client.tools.retrieve.return_value = github_tool
369
+
370
+ # Mock the client's execute method
371
+ mock_execute_response = Mock()
372
+ mock_execute_response.model_dump.return_value = {
373
+ "data": {"result": "success"},
374
+ "error": None,
375
+ "successful": True,
376
+ }
377
+ mock_client.tools.execute.return_value = mock_execute_response
378
+
379
+ # Execute should succeed with dangerously_skip_version_check=True
380
+ result = tools.execute(
381
+ slug="GITHUB_GET_REPOS",
382
+ arguments={"owner": "test", "repo": "test"},
383
+ dangerously_skip_version_check=True,
384
+ )
385
+
386
+ # Verify execution succeeded
387
+ assert result["successful"] is True
388
+ assert result["data"] == {"result": "success"}
389
+
390
+ # Verify the client was called with version="latest"
391
+ mock_client.tools.execute.assert_called_once()
392
+ call_args = mock_client.tools.execute.call_args
393
+ assert call_args.kwargs["version"] == "latest"
394
+
395
+ def test_execute_with_specific_version_no_error(self):
396
+ """Test that execute works with specific version without raising error."""
397
+ # Mock client and provider
398
+ mock_client = Mock()
399
+ mock_provider = Mock()
400
+ mock_provider.name = "test_provider"
401
+
402
+ # Create Tools instance without toolkit versions
403
+ tools = Tools(
404
+ client=mock_client,
405
+ provider=mock_provider,
406
+ )
407
+
408
+ # Create a mock GitHub tool
409
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
410
+
411
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
412
+ with patch.object(
413
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
414
+ ):
415
+ mock_client.tools.retrieve.return_value = github_tool
416
+
417
+ # Mock the client's execute method
418
+ mock_execute_response = Mock()
419
+ mock_execute_response.model_dump.return_value = {
420
+ "data": {"result": "success"},
421
+ "error": None,
422
+ "successful": True,
423
+ }
424
+ mock_client.tools.execute.return_value = mock_execute_response
425
+
426
+ # Execute with specific version should succeed
427
+ result = tools.execute(
428
+ slug="GITHUB_GET_REPOS",
429
+ arguments={"owner": "test", "repo": "test"},
430
+ version="20251201_01",
431
+ )
432
+
433
+ # Verify execution succeeded
434
+ assert result["successful"] is True
435
+
436
+ # Verify the client was called with the specific version
437
+ mock_client.tools.execute.assert_called_once()
438
+ call_args = mock_client.tools.execute.call_args
439
+ assert call_args.kwargs["version"] == "20251201_01"
440
+
441
+ def test_execute_uses_instance_toolkit_versions(self):
442
+ """Test that execute method uses instance-level toolkit versions."""
443
+ # Mock client and provider
444
+ mock_client = Mock()
445
+ mock_provider = Mock()
446
+ mock_provider.name = "test_provider"
447
+
448
+ # Create toolkit versions configuration
449
+ toolkit_versions = {"github": "20251201_01", "slack": "20251201_02"}
450
+
451
+ # Create Tools instance with toolkit versions
452
+ tools = Tools(
453
+ client=mock_client,
454
+ provider=mock_provider,
455
+ toolkit_versions=toolkit_versions,
456
+ )
457
+
458
+ # Create a mock GitHub tool
459
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
460
+
461
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
462
+ with patch.object(
463
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
464
+ ):
465
+ mock_client.tools.retrieve.return_value = github_tool
466
+
467
+ # Mock the client's execute method
468
+ mock_execute_response = Mock()
469
+ mock_execute_response.model_dump.return_value = {
470
+ "data": {"result": "success"},
471
+ "error": None,
472
+ "successful": True,
473
+ }
474
+ mock_client.tools.execute.return_value = mock_execute_response
475
+
476
+ # Execute should use the configured toolkit version
477
+ result = tools.execute(
478
+ slug="GITHUB_GET_REPOS",
479
+ arguments={"owner": "test", "repo": "test"},
480
+ )
481
+
482
+ # Verify execution succeeded
483
+ assert result["successful"] is True
484
+
485
+ # Verify the client was called with the configured version
486
+ mock_client.tools.execute.assert_called_once()
487
+ call_args = mock_client.tools.execute.call_args
488
+ assert call_args.kwargs["version"] == "20251201_01"
489
+
490
+ def test_execute_version_parameter_overrides_toolkit_versions(self):
491
+ """Test that explicit version parameter overrides instance toolkit versions."""
492
+ # Mock client and provider
493
+ mock_client = Mock()
494
+ mock_provider = Mock()
495
+ mock_provider.name = "test_provider"
496
+
497
+ # Create toolkit versions configuration
498
+ toolkit_versions = {"github": "20251201_01"}
499
+
500
+ # Create Tools instance with toolkit versions
501
+ tools = Tools(
502
+ client=mock_client,
503
+ provider=mock_provider,
504
+ toolkit_versions=toolkit_versions,
505
+ )
506
+
507
+ # Create a mock GitHub tool
508
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
509
+
510
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
511
+ with patch.object(
512
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
513
+ ):
514
+ mock_client.tools.retrieve.return_value = github_tool
515
+
516
+ # Mock the client's execute method
517
+ mock_execute_response = Mock()
518
+ mock_execute_response.model_dump.return_value = {
519
+ "data": {"result": "success"},
520
+ "error": None,
521
+ "successful": True,
522
+ }
523
+ mock_client.tools.execute.return_value = mock_execute_response
524
+
525
+ # Execute with explicit version should override instance version
526
+ result = tools.execute(
527
+ slug="GITHUB_GET_REPOS",
528
+ arguments={"owner": "test", "repo": "test"},
529
+ version="20251201_03", # Explicit version
530
+ )
531
+
532
+ # Verify execution succeeded
533
+ assert result["successful"] is True
534
+
535
+ # Verify the client was called with the explicit version, not instance version
536
+ mock_client.tools.execute.assert_called_once()
537
+ call_args = mock_client.tools.execute.call_args
538
+ assert call_args.kwargs["version"] == "20251201_03"
539
+
540
+ def test_execute_with_connected_account_id(self):
541
+ """Test that execute passes connected_account_id correctly."""
542
+ # Mock client and provider
543
+ mock_client = Mock()
544
+ mock_provider = Mock()
545
+ mock_provider.name = "test_provider"
546
+
547
+ # Create Tools instance with toolkit versions
548
+ tools = Tools(
549
+ client=mock_client,
550
+ provider=mock_provider,
551
+ toolkit_versions={"github": "20251201_01"},
552
+ )
553
+
554
+ # Create a mock GitHub tool
555
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
556
+
557
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
558
+ with patch.object(
559
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
560
+ ):
561
+ mock_client.tools.retrieve.return_value = github_tool
562
+
563
+ # Mock the client's execute method
564
+ mock_execute_response = Mock()
565
+ mock_execute_response.model_dump.return_value = {
566
+ "data": {"result": "success"},
567
+ "error": None,
568
+ "successful": True,
569
+ }
570
+ mock_client.tools.execute.return_value = mock_execute_response
571
+
572
+ # Execute with connected_account_id
573
+ result = tools.execute(
574
+ slug="GITHUB_GET_REPOS",
575
+ arguments={"owner": "test", "repo": "test"},
576
+ connected_account_id="test-account-123",
577
+ )
578
+
579
+ # Verify execution succeeded
580
+ assert result["successful"] is True
581
+
582
+ # Verify the client was called with the connected_account_id
583
+ mock_client.tools.execute.assert_called_once()
584
+ call_args = mock_client.tools.execute.call_args
585
+ assert call_args.kwargs["connected_account_id"] == "test-account-123"
586
+
587
+ def test_execute_with_custom_auth_params(self):
588
+ """Test that execute passes custom_auth_params correctly."""
589
+ # Mock client and provider
590
+ mock_client = Mock()
591
+ mock_provider = Mock()
592
+ mock_provider.name = "test_provider"
593
+
594
+ # Create Tools instance with toolkit versions
595
+ tools = Tools(
596
+ client=mock_client,
597
+ provider=mock_provider,
598
+ toolkit_versions={"github": "20251201_01"},
599
+ )
600
+
601
+ # Create a mock GitHub tool
602
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
603
+
604
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
605
+ with patch.object(
606
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
607
+ ):
608
+ mock_client.tools.retrieve.return_value = github_tool
609
+
610
+ # Mock the client's execute method
611
+ mock_execute_response = Mock()
612
+ mock_execute_response.model_dump.return_value = {
613
+ "data": {"result": "success"},
614
+ "error": None,
615
+ "successful": True,
616
+ }
617
+ mock_client.tools.execute.return_value = mock_execute_response
618
+
619
+ # Execute with custom_auth_params
620
+ custom_auth = {"api_key": "test-key"}
621
+ result = tools.execute(
622
+ slug="GITHUB_GET_REPOS",
623
+ arguments={"owner": "test", "repo": "test"},
624
+ custom_auth_params=custom_auth,
625
+ )
626
+
627
+ # Verify execution succeeded
628
+ assert result["successful"] is True
629
+
630
+ # Verify the client was called with the custom_auth_params
631
+ mock_client.tools.execute.assert_called_once()
632
+ call_args = mock_client.tools.execute.call_args
633
+ assert call_args.kwargs["custom_auth_params"] == custom_auth
634
+
635
+ def test_execute_with_user_id_and_text(self):
636
+ """Test that execute passes user_id and text parameters correctly."""
637
+ # Mock client and provider
638
+ mock_client = Mock()
639
+ mock_provider = Mock()
640
+ mock_provider.name = "test_provider"
641
+
642
+ # Create Tools instance with toolkit versions
643
+ tools = Tools(
644
+ client=mock_client,
645
+ provider=mock_provider,
646
+ toolkit_versions={"github": "20251201_01"},
647
+ )
648
+
649
+ # Create a mock GitHub tool
650
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
651
+
652
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
653
+ with patch.object(
654
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
655
+ ):
656
+ mock_client.tools.retrieve.return_value = github_tool
657
+
658
+ # Mock the client's execute method
659
+ mock_execute_response = Mock()
660
+ mock_execute_response.model_dump.return_value = {
661
+ "data": {"result": "success"},
662
+ "error": None,
663
+ "successful": True,
664
+ }
665
+ mock_client.tools.execute.return_value = mock_execute_response
666
+
667
+ # Execute with user_id and text
668
+ result = tools.execute(
669
+ slug="GITHUB_GET_REPOS",
670
+ arguments={"owner": "test", "repo": "test"},
671
+ user_id="user-123",
672
+ text="Additional context",
673
+ )
674
+
675
+ # Verify execution succeeded
676
+ assert result["successful"] is True
677
+
678
+ # Verify the client was called with user_id and text
679
+ mock_client.tools.execute.assert_called_once()
680
+ call_args = mock_client.tools.execute.call_args
681
+ assert call_args.kwargs["user_id"] == "user-123"
682
+ assert call_args.kwargs["text"] == "Additional context"
683
+
684
+ def test_execute_custom_tool(self):
685
+ """Test that execute works with custom tools."""
686
+ # Mock client and provider
687
+ mock_client = Mock()
688
+ mock_provider = Mock()
689
+ mock_provider.name = "test_provider"
690
+
691
+ # Create Tools instance
692
+ tools = Tools(
693
+ client=mock_client,
694
+ provider=mock_provider,
695
+ toolkit_versions={"custom": "20251201_01"},
696
+ )
697
+
698
+ # Create a mock custom tool with proper structure
699
+ custom_tool_info = self.create_mock_tool("CUSTOM_TOOL", "custom")
700
+ custom_tool_info.input_parameters = {"type": "object", "properties": {}}
701
+
702
+ # Mock the custom tool registry
703
+ mock_custom_tool = Mock()
704
+ mock_custom_tool.info = custom_tool_info
705
+ tools._custom_tools.custom_tools_registry = {"CUSTOM_TOOL": mock_custom_tool}
706
+
707
+ # Mock the get method to return the tool
708
+ def mock_get(slug):
709
+ return mock_custom_tool if slug == "CUSTOM_TOOL" else None
710
+
711
+ tools._custom_tools.get = Mock(side_effect=mock_get)
712
+
713
+ # Mock the execute method of custom tool
714
+ def mock_execute(slug, request, user_id):
715
+ return {"custom_result": "success"}
716
+
717
+ tools._custom_tools.execute = Mock(side_effect=mock_execute)
718
+
719
+ # Execute the custom tool
720
+ result = tools.execute(
721
+ slug="CUSTOM_TOOL",
722
+ arguments={"param": "value"},
723
+ user_id="user-123",
724
+ )
725
+
726
+ # Verify execution succeeded
727
+ assert result["successful"] is True
728
+ assert result["data"]["custom_result"] == "success"
729
+
730
+ # Verify custom tool execute was called
731
+ tools._custom_tools.execute.assert_called_once_with(
732
+ slug="CUSTOM_TOOL",
733
+ request={"param": "value"},
734
+ user_id="user-123",
735
+ )
736
+
737
+ def test_execute_with_modifiers_before_execute(self):
738
+ """Test that execute applies before_execute modifiers correctly."""
739
+ from composio.core.models._modifiers import before_execute
740
+
741
+ # Mock client and provider
742
+ mock_client = Mock()
743
+ mock_provider = Mock()
744
+ mock_provider.name = "test_provider"
745
+
746
+ # Create Tools instance with toolkit versions
747
+ tools = Tools(
748
+ client=mock_client,
749
+ provider=mock_provider,
750
+ toolkit_versions={"github": "20251201_01"},
751
+ )
752
+
753
+ # Create a mock GitHub tool
754
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
755
+
756
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
757
+ with patch.object(
758
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
759
+ ):
760
+ mock_client.tools.retrieve.return_value = github_tool
761
+
762
+ # Mock the client's execute method
763
+ mock_execute_response = Mock()
764
+ mock_execute_response.model_dump.return_value = {
765
+ "data": {"result": "success"},
766
+ "error": None,
767
+ "successful": True,
768
+ }
769
+ mock_client.tools.execute.return_value = mock_execute_response
770
+
771
+ # Create a before_execute modifier that changes the arguments
772
+ def modify_arguments(tool, toolkit, params):
773
+ params["arguments"]["owner"] = "modified-owner"
774
+ return params
775
+
776
+ modifier = before_execute(modify_arguments)
777
+
778
+ # Execute with modifier
779
+ result = tools.execute(
780
+ slug="GITHUB_GET_REPOS",
781
+ arguments={"owner": "test", "repo": "test"},
782
+ modifiers=[modifier],
783
+ )
784
+
785
+ # Verify execution succeeded
786
+ assert result["successful"] is True
787
+
788
+ # Verify the client was called with modified arguments
789
+ mock_client.tools.execute.assert_called_once()
790
+ call_args = mock_client.tools.execute.call_args
791
+ assert call_args.kwargs["arguments"]["owner"] == "modified-owner"
792
+
793
+ def test_execute_with_modifiers_after_execute(self):
794
+ """Test that execute applies after_execute modifiers correctly."""
795
+ from composio.core.models._modifiers import after_execute
796
+
797
+ # Mock client and provider
798
+ mock_client = Mock()
799
+ mock_provider = Mock()
800
+ mock_provider.name = "test_provider"
801
+
802
+ # Create Tools instance with toolkit versions
803
+ tools = Tools(
804
+ client=mock_client,
805
+ provider=mock_provider,
806
+ toolkit_versions={"github": "20251201_01"},
807
+ )
808
+
809
+ # Create a mock GitHub tool
810
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
811
+
812
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
813
+ with patch.object(
814
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
815
+ ):
816
+ mock_client.tools.retrieve.return_value = github_tool
817
+
818
+ # Mock the client's execute method
819
+ mock_execute_response = Mock()
820
+ mock_execute_response.model_dump.return_value = {
821
+ "data": {"result": "success"},
822
+ "error": None,
823
+ "successful": True,
824
+ }
825
+ mock_client.tools.execute.return_value = mock_execute_response
826
+
827
+ # Create an after_execute modifier that modifies the response
828
+ def modify_response(tool, toolkit, response):
829
+ response["data"]["modified"] = True
830
+ return response
831
+
832
+ modifier = after_execute(modify_response)
833
+
834
+ # Execute with modifier
835
+ result = tools.execute(
836
+ slug="GITHUB_GET_REPOS",
837
+ arguments={"owner": "test", "repo": "test"},
838
+ modifiers=[modifier],
839
+ )
840
+
841
+ # Verify execution succeeded and response was modified
842
+ assert result["successful"] is True
843
+ assert result["data"]["modified"] is True
844
+
845
+ def test_execute_with_environment_variable_toolkit_version(self):
846
+ """Test that execute uses environment variable for toolkit version."""
847
+ import os
848
+
849
+ # Mock client and provider
850
+ mock_client = Mock()
851
+ mock_provider = Mock()
852
+ mock_provider.name = "test_provider"
853
+
854
+ # Set environment variable for github toolkit version
855
+ os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"] = "20251201_08"
856
+
857
+ try:
858
+ # Create Tools instance with explicit toolkit versions that match the env var
859
+ # This simulates what happens when get_toolkit_version reads the env var
860
+ tools = Tools(
861
+ client=mock_client,
862
+ provider=mock_provider,
863
+ toolkit_versions={"github": "20251201_08"}, # This matches the env var
864
+ )
865
+
866
+ # Create a mock GitHub tool with proper structure
867
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
868
+ github_tool.input_parameters = {"type": "object", "properties": {}}
869
+
870
+ # Mock the retrieve method
871
+ mock_client.tools.retrieve.return_value = github_tool
872
+
873
+ # Mock the client's execute method
874
+ mock_execute_response = Mock()
875
+ mock_execute_response.model_dump.return_value = {
876
+ "data": {"result": "success"},
877
+ "error": None,
878
+ "successful": True,
879
+ }
880
+ mock_client.tools.execute.return_value = mock_execute_response
881
+
882
+ # Execute should use the environment variable version
883
+ result = tools.execute(
884
+ slug="GITHUB_GET_REPOS",
885
+ arguments={"owner": "test", "repo": "test"},
886
+ )
887
+
888
+ # Verify execution succeeded
889
+ assert result["successful"] is True
890
+
891
+ # Verify the client was called with the env variable version
892
+ mock_client.tools.execute.assert_called_once()
893
+ call_args = mock_client.tools.execute.call_args
894
+ assert call_args.kwargs["version"] == "20251201_08"
895
+ finally:
896
+ # Clean up environment variable
897
+ if "COMPOSIO_TOOLKIT_VERSION_GITHUB" in os.environ:
898
+ del os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"]
899
+
900
+ def test_execute_raises_error_with_latest_via_env_variable(self):
901
+ """Test that execute raises error when env variable sets version to 'latest'."""
902
+ import os
903
+
904
+ # Mock client and provider
905
+ mock_client = Mock()
906
+ mock_provider = Mock()
907
+ mock_provider.name = "test_provider"
908
+
909
+ # Set environment variable for github toolkit version to 'latest'
910
+ os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"] = "latest"
911
+
912
+ try:
913
+ # Create Tools instance without explicit toolkit versions
914
+ tools = Tools(
915
+ client=mock_client,
916
+ provider=mock_provider,
917
+ )
918
+
919
+ # Create a mock GitHub tool with proper structure
920
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
921
+ github_tool.input_parameters = {"type": "object", "properties": {}}
922
+
923
+ # Mock the retrieve method
924
+ mock_client.tools.retrieve.return_value = github_tool
925
+
926
+ # Execute should raise ToolVersionRequiredError since version is 'latest'
927
+ with pytest.raises(ToolVersionRequiredError):
928
+ tools.execute(
929
+ slug="GITHUB_GET_REPOS",
930
+ arguments={"owner": "test", "repo": "test"},
931
+ )
932
+ finally:
933
+ # Clean up environment variable
934
+ if "COMPOSIO_TOOLKIT_VERSION_GITHUB" in os.environ:
935
+ del os.environ["COMPOSIO_TOOLKIT_VERSION_GITHUB"]
936
+
937
+ def test_execute_with_custom_connection_data(self):
938
+ """Test that execute passes custom_connection_data correctly."""
939
+ # Mock client and provider
940
+ mock_client = Mock()
941
+ mock_provider = Mock()
942
+ mock_provider.name = "test_provider"
943
+
944
+ # Create Tools instance with toolkit versions
945
+ tools = Tools(
946
+ client=mock_client,
947
+ provider=mock_provider,
948
+ toolkit_versions={"github": "20251201_01"},
949
+ )
950
+
951
+ # Create a mock GitHub tool
952
+ github_tool = self.create_mock_tool("GITHUB_GET_REPOS", "github")
953
+
954
+ # Mock the get_raw_composio_tool_by_slug and retrieve methods
955
+ with patch.object(
956
+ tools, "get_raw_composio_tool_by_slug", return_value=github_tool
957
+ ):
958
+ mock_client.tools.retrieve.return_value = github_tool
959
+
960
+ # Mock the client's execute method
961
+ mock_execute_response = Mock()
962
+ mock_execute_response.model_dump.return_value = {
963
+ "data": {"result": "success"},
964
+ "error": None,
965
+ "successful": True,
966
+ }
967
+ mock_client.tools.execute.return_value = mock_execute_response
968
+
969
+ # Execute with custom_connection_data
970
+ custom_connection = {"token": "custom-token"}
971
+ result = tools.execute(
972
+ slug="GITHUB_GET_REPOS",
973
+ arguments={"owner": "test", "repo": "test"},
974
+ custom_connection_data=custom_connection,
975
+ )
976
+
977
+ # Verify execution succeeded
978
+ assert result["successful"] is True
979
+
980
+ # Verify the client was called with custom_connection_data
981
+ mock_client.tools.execute.assert_called_once()
982
+ call_args = mock_client.tools.execute.call_args
983
+ assert call_args.kwargs["custom_connection_data"] == custom_connection
ts/packages/core/src/composio.ts
+34
-6
@@ -76,12 +76,40 @@ export type ComposioConfig<
76
*/
77
disableVersionCheck?: boolean;
78
/**
79
- * The versions of the toolkits to fetch.
80
- * Defaults to latest is nothing is provided.
81
- * Alternatively you can specify individual toolkit versions in the env `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
82
- * @example
83
- * { 'github': 'latest', 'slack': '20250902_00' }
84
- * 'latest'
79
+ * The versions of the toolkits to use for tool execution and retrieval.
80
+ *
81
+ * **Version Control:**
82
+ * When executing tools manually (via `tools.execute()`), if this resolves to "latest",
83
+ * you must either:
84
+ * - Set `dangerouslySkipVersionCheck: true` in the execute params (not recommended for production)
85
+ * - Specify a concrete version here or in environment variables
86
+ * - Pass a specific `version` parameter to the execute call
87
+ *
88
+ * Defaults to 'latest' if nothing is provided.
89
+ * You can specify individual toolkit versions via environment variables: `COMPOSIO_TOOLKIT_VERSION_GITHUB=20250902_00`
90
+ *
91
+ * @example Global version for all toolkits
92
+ * ```typescript
93
+ * const composio = new Composio({ toolkitVersions: 'latest' });
94
+ * ```
95
+ *
96
+ * @example Specific versions for different toolkits (recommended for production)
97
+ * ```typescript
98
+ * const composio = new Composio({
99
+ * toolkitVersions: {
100
+ * github: '20250909_00',
101
+ * slack: '20250902_00'
102
+ * }
103
+ * });
104
+ * ```
105
+ *
106
+ * @example Set via environment variables
107
+ * ```typescript
108
+ * // Set environment variables:
109
+ * // COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00
110
+ * // COMPOSIO_TOOLKIT_VERSION_SLACK=20250902_00
111
+ * const composio = new Composio(); // Will use env variables
112
+ * ```
113
*/
114
toolkitVersions?: ToolkitVersionParam;
115
};
ts/packages/core/src/errors/ToolErrors.ts
+81
@@ -10,6 +10,7 @@ export const ToolErrorCodes = {
10
TOOL_EXECUTION_ERROR: 'TOOL_EXECUTION_ERROR',
11
INVALID_EXECUTE_FUNCTION: 'INVALID_EXECUTE_FUNCTION',
12
GLOBAL_EXECUTE_TOOL_FN_NOT_SET: 'GLOBAL_EXECUTE_TOOL_FN_NOT_SET',
13
+ TOOL_VERSION_REQUIRED: 'TOOL_VERSION_REQUIRED',
14
} as const;
15
16
export class ComposioProviderNotDefinedError extends ComposioError {
@@ -124,6 +125,86 @@ export class ComposioGlobalExecuteToolFnNotSetError extends ComposioError {
125
}
126
}
127
128
+/**
129
+ * Error thrown when toolkit version is not specified for manual tool execution.
130
+ *
131
+ * This error is thrown when attempting to execute a tool manually (via `tools.execute()`)
132
+ * and the resolved version is "latest" without `dangerouslySkipVersionCheck` set to true.
133
+ *
134
+ * **Why this error exists:**
135
+ * Using "latest" version in manual execution can lead to unexpected behavior when new
136
+ * toolkit versions are released, potentially breaking your application. For production
137
+ * use, it's recommended to pin specific toolkit versions.
138
+ *
139
+ * **How to fix:**
140
+ * 1. Specify a concrete version in the execute call
141
+ * 2. Configure toolkit versions at SDK initialization
142
+ * 3. Set toolkit version via environment variable
143
+ * 4. Use dangerouslySkipVersionCheck (not recommended for production)
144
+ *
145
+ * @example ❌ This will throw ComposioToolVersionRequiredError if toolkitVersions is 'latest'
146
+ * ```typescript
147
+ * await composio.tools.execute('GITHUB_GET_REPOS', {
148
+ * userId: 'default',
149
+ * arguments: { owner: 'composio' }
150
+ * });
151
+ * ```
152
+ *
153
+ * @example ✅ Fix 1: Pass specific version in execute call
154
+ * ```typescript
155
+ * await composio.tools.execute('GITHUB_GET_REPOS', {
156
+ * userId: 'default',
157
+ * version: '20250909_00',
158
+ * arguments: { owner: 'composio' }
159
+ * });
160
+ * ```
161
+ *
162
+ * @example ✅ Fix 2: Configure toolkit versions at SDK level
163
+ * ```typescript
164
+ * const composio = new Composio({
165
+ * toolkitVersions: { github: '20250909_00' }
166
+ * });
167
+ * await composio.tools.execute('GITHUB_GET_REPOS', {
168
+ * userId: 'default',
169
+ * arguments: { owner: 'composio' }
170
+ * });
171
+ * ```
172
+ *
173
+ * @example ✅ Fix 3: Use environment variable
174
+ * ```typescript
175
+ * // Set: COMPOSIO_TOOLKIT_VERSION_GITHUB=20250909_00
176
+ * await composio.tools.execute('GITHUB_GET_REPOS', {
177
+ * userId: 'default',
178
+ * arguments: { owner: 'composio' }
179
+ * });
180
+ * ```
181
+ *
182
+ * @example ⚠️ Fix 4: Skip version check (not recommended for production)
183
+ * ```typescript
184
+ * await composio.tools.execute('GITHUB_GET_REPOS', {
185
+ * userId: 'default',
186
+ * dangerouslySkipVersionCheck: true,
187
+ * arguments: { owner: 'composio' }
188
+ * });
189
+ * ```
190
+ */
191
+export class ComposioToolVersionRequiredError extends ComposioError {
192
+ constructor(
193
+ message: string = 'Toolkit version not specified. For manual execution of the tool please pass a specific toolkit version',
194
+ options: Omit<ComposioErrorOptions, 'code'> = {}
195
+ ) {
196
+ super(message, {
197
+ ...options,
198
+ code: ToolErrorCodes.TOOL_VERSION_REQUIRED,
199
+ possibleFixes: options.possibleFixes || [
200
+ 'Pass the toolkit version as a parameter to the execute function ("latest" is not supported in manual execution)',
201
+ 'Set the toolkit versions in the Composio config (toolkitVersions: { <toolkit-slug>: "<toolkit-version>" })',
202
+ 'Set the toolkit version in the environment variable (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>)',
203
+ 'Set dangerouslySkipVersionCheck to true (this might cause unexpected behavior when new versions of the tools are released)',
204
+ ],
205
+ });
206
+ }
207
+}
208
export interface ComposioAPIServerErrorBody {
209
error: {
210
message: string;
ts/packages/core/src/models/Tools.ts
+53
-10
@@ -42,6 +42,7 @@ import {
42
ComposioInvalidModifierError,
43
ComposioToolNotFoundError,
44
ComposioProviderNotDefinedError,
45
+ ComposioToolVersionRequiredError,
46
} from '../errors/ToolErrors';
47
import { ValidationError } from '../errors/ValidationErrors';
48
import { telemetry } from '../telemetry/Telemetry';
@@ -599,6 +600,9 @@ export class Tools<
600
{
601
userId,
602
arguments: input,
603
+ // dangerously skip version check for agentic and non agentic tool execution via providers
604
+ // this can be safe because most agentic flows users fetch latest version and then execute the tool
605
+ dangerouslySkipVersionCheck: true,
606
},
607
modifiers
608
);
@@ -617,6 +621,12 @@ export class Tools<
621
tool: Tool,
622
body: ToolExecuteParams
623
): Promise<ToolExecuteResponse> {
624
+ const toolkitVersion =
625
+ body.version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions);
626
+ // if the version is latest and dangerouslySkipVersionCheck is not true, throw an error
627
+ if (toolkitVersion === 'latest' && !body.dangerouslySkipVersionCheck) {
628
+ throw new ComposioToolVersionRequiredError();
629
+ }
630
try {
631
const result = await this.client.tools.execute(tool.slug, {
632
allow_tracing: body.allowTracing,
@@ -625,8 +635,7 @@ export class Tools<
635
custom_connection_data: body.customConnectionData,
636
arguments: body.arguments,
637
user_id: body.userId,
628
- version:
629
- body.version ?? getToolkitVersion(tool.toolkit?.slug ?? 'unknown', this.toolkitVersions),
638
+ version: toolkitVersion,
639
text: body.text,
640
});
641
// transform the response to the ToolExecuteResponse format
@@ -643,34 +652,68 @@ export class Tools<
652
* This method calls the Composio API or a custom tool handler to execute the tool and returns the response.
653
* It automatically determines whether to use a custom tool or a Composio API tool based on the slug.
654
*
655
+ * **Version Control:**
656
+ * By default, manual tool execution requires a specific toolkit version. If the version resolves to "latest",
657
+ * the execution will throw a `ComposioToolVersionRequiredError` unless `dangerouslySkipVersionCheck` is set to `true`.
658
+ * This helps prevent unexpected behavior when new toolkit versions are released.
659
+ *
660
* @param {string} slug - The slug/ID of the tool to be executed
661
* @param {ToolExecuteParams} body - The parameters to be passed to the tool
662
+ * @param {string} [body.version] - The specific version of the tool to execute (e.g., "20250909_00")
663
+ * @param {boolean} [body.dangerouslySkipVersionCheck] - Skip version validation for "latest" version (use with caution)
664
+ * @param {string} [body.userId] - The user ID to execute the tool for
665
+ * @param {string} [body.connectedAccountId] - The connected account ID to use for authenticated tools
666
+ * @param {Record<string, unknown>} [body.arguments] - The arguments to pass to the tool
667
* @param {ExecuteToolModifiers} [modifiers] - Optional modifiers to transform the request or response
668
* @returns {Promise<ToolExecuteResponse>} - The response from the tool execution
669
*
670
* @throws {ComposioCustomToolsNotInitializedError} If the CustomTools instance is not initialized
671
+ * @throws {ComposioConnectedAccountNotFoundError} If the connected account is not found
672
* @throws {ComposioToolNotFoundError} If the tool with the given slug is not found
673
+ * @throws {ComposioToolVersionRequiredError} If version resolves to "latest" and dangerouslySkipVersionCheck is not true
674
* @throws {ComposioToolExecutionError} If there is an error during tool execution
675
*
655
- * @example
676
+ * @example Execute with a specific version (recommended for production)
677
+ * ```typescript
678
+ * const result = await composio.tools.execute('GITHUB_GET_REPOS', {
679
+ * userId: 'default',
680
+ * version: '20250909_00',
681
+ * arguments: { owner: 'composio' }
682
+ * });
683
+ * ```
684
+ *
685
+ * @example Execute with dangerouslySkipVersionCheck (not recommended for production)
686
* ```typescript
657
- * // Execute a Composio API tool
687
* const result = await composio.tools.execute('HACKERNEWS_GET_USER', {
688
* userId: 'default',
660
- * arguments: { userId: 'pg' }
689
+ * arguments: { userId: 'pg' },
690
+ * dangerouslySkipVersionCheck: true // Allows execution with "latest" version
691
* });
692
+ * ```
693
*
663
- * // Execute with modifiers
694
+ * @example Execute with SDK-level toolkit versions configuration
695
+ * ```typescript
696
+ * // If toolkitVersions are set during Composio initialization, no need to pass version
697
+ * const composio = new Composio({ toolkitVersions: { github: '20250909_00' } });
698
+ * const result = await composio.tools.execute('GITHUB_GET_REPOS', {
699
+ * userId: 'default',
700
+ * arguments: { owner: 'composio' }
701
+ * });
702
+ * ```
703
+ *
704
+ * @example Execute with modifiers
705
+ * ```typescript
706
* const result = await composio.tools.execute('GITHUB_GET_ISSUES', {
707
* userId: 'default',
708
+ * version: '20250909_00',
709
* arguments: { owner: 'composio', repo: 'sdk' }
710
* }, {
668
- * beforeExecute: (toolSlug, toolkitSlug, params) => {
669
- * // Modify params before execution
711
+ * beforeExecute: ({ toolSlug, toolkitSlug, params }) => {
712
+ * console.log(`Executing ${toolSlug} from ${toolkitSlug}`);
713
* return params;
714
* },
672
- * afterExecute: (toolSlug, toolkitSlug, result) => {
673
- * // Transform result after execution
715
+ * afterExecute: ({ toolSlug, toolkitSlug, result }) => {
716
+ * console.log(`Completed ${toolSlug}`);
717
* return result;
718
* }
719
* });
ts/packages/core/src/types/tool.types.ts
+36
-2
@@ -257,7 +257,40 @@ export const CustomAuthParamsSchema = z.object({
257
export type CustomAuthParams = z.infer<typeof CustomAuthParamsSchema>;
258
259
/**
260
- * ToolExecuteParams is the parameters for the tool execution.
260
+ * Parameters for tool execution.
261
+ *
262
+ * @property {boolean} [allowTracing] - Enable tracing for this tool execution
263
+ * @property {string} [connectedAccountId] - The connected account ID to use for authenticated tools
264
+ * @property {CustomAuthParams} [customAuthParams] - Custom authentication parameters
265
+ * @property {CustomConnectionData} [customConnectionData] - Custom connection data (takes priority over customAuthParams)
266
+ * @property {Record<string, unknown>} [arguments] - The arguments to pass to the tool
267
+ * @property {string} [userId] - The user ID to execute the tool for (required for no-auth apps)
268
+ * @property {string} [version] - The specific version of the tool to execute (e.g., "20250909_00" or "latest")
269
+ * @property {boolean} [dangerouslySkipVersionCheck] - Skip version validation when using "latest" version.
270
+ * **Warning:** This may cause unexpected behavior when new toolkit versions are released.
271
+ * Only use this if you understand the risks. Recommended alternatives:
272
+ * - Specify a concrete version in the `version` parameter
273
+ * - Configure toolkit versions at SDK initialization level
274
+ * - Set toolkit version via environment variable (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>)
275
+ * @property {string} [text] - Additional text input for the tool
276
+ *
277
+ * @example Recommended: Execute with a specific version
278
+ * ```typescript
279
+ * const params: ToolExecuteParams = {
280
+ * userId: 'default',
281
+ * version: '20250909_00',
282
+ * arguments: { owner: 'composio', repo: 'sdk' }
283
+ * };
284
+ * ```
285
+ *
286
+ * @example With dangerouslySkipVersionCheck (use with caution)
287
+ * ```typescript
288
+ * const params: ToolExecuteParams = {
289
+ * userId: 'default',
290
+ * dangerouslySkipVersionCheck: true,
291
+ * arguments: { userId: 'pg' }
292
+ * };
293
+ * ```
294
*/
295
export const ToolExecuteParamsSchema = z.object({
296
allowTracing: z.boolean().optional(),
@@ -265,8 +298,9 @@ export const ToolExecuteParamsSchema = z.object({
298
customAuthParams: CustomAuthParamsSchema.optional(),
299
customConnectionData: CustomConnectionDataSchema.optional(),
300
arguments: z.record(z.string(), z.unknown()).optional(),
268
- userId: z.string().optional(), // we have no auth apps which can be execute
301
+ userId: z.string().optional(),
302
version: z.union([z.literal('latest'), z.string()]).optional(),
303
+ dangerouslySkipVersionCheck: z.boolean().optional(),
304
text: z.string().optional(),
305
});
306
export type ToolExecuteParams = z.infer<typeof ToolExecuteParamsSchema>;
ts/packages/core/test/tools/fileModifiers.test.ts
+14
-12
@@ -37,8 +37,8 @@ describe('FileToolModifier', () => {
37
name: 'Test Tool',
38
description: 'A test tool',
39
tags: ['test'],
40
- version: '20250902_00',
41
- availableVersions: ['20250902_00'],
40
+ version: '20251201_01',
41
+ availableVersions: ['20251201_01'],
42
};
43
44
const result = await fileToolModifier.modifyToolSchema('test-tool', 'test-toolkit', schema);
@@ -51,8 +51,8 @@ describe('FileToolModifier', () => {
51
name: 'Test Tool',
52
description: 'A test tool',
53
tags: ['test'],
54
- version: '20250902_00',
55
- availableVersions: ['20250902_00'],
54
+ version: '20251201_01',
55
+ availableVersions: ['20251201_01'],
56
inputParameters: {
57
type: 'object',
58
properties: {
@@ -91,8 +91,8 @@ describe('FileToolModifier', () => {
91
},
92
},
93
},
94
- version: '20250902_00',
95
- availableVersions: ['20250902_00'],
94
+ version: '20251201_01',
95
+ availableVersions: ['20251201_01'],
96
};
97
98
it('should upload file for file_uploadable parameters', async () => {
@@ -186,8 +186,8 @@ describe('FileToolModifier', () => {
186
name: 'Test Tool',
187
description: 'A test tool',
188
tags: ['test'],
189
- availableVersions: ['20250902_00'],
190
- version: '20250902_00',
189
+ availableVersions: ['20251201_01'],
190
+ version: '20251201_01',
191
};
192
193
it('should download file from S3 URL', async () => {
@@ -322,8 +322,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
322
},
323
additionalProperties: false,
324
},
325
- version: '20250902_00',
326
- availableVersions: ['20250902_00'],
325
+ version: '20251201_01',
326
+ availableVersions: ['20251201_01'],
327
};
328
329
const mockRawToolWithFileUpload = {
@@ -362,8 +362,8 @@ describe('Tools with autoUploadDownloadFiles', () => {
362
},
363
additionalProperties: false,
364
},
365
- version: '20250902_00',
366
- availableVersions: ['20250902_00'],
365
+ version: '20251201_01',
366
+ availableVersions: ['20251201_01'],
367
};
368
369
describe('when autoUploadDownloadFiles is false', () => {
@@ -418,6 +418,7 @@ describe('Tools with autoUploadDownloadFiles', () => {
418
file: '/path/to/file.txt',
419
},
420
userId: 'test-user',
421
+ dangerouslySkipVersionCheck: true,
422
});
423
424
expect(fileUtils.getFileDataAfterUploadingToS3).not.toHaveBeenCalled();
@@ -472,6 +473,7 @@ describe('Tools with autoUploadDownloadFiles', () => {
473
file: '/path/to/file.txt',
474
},
475
userId: 'test-user',
476
+ dangerouslySkipVersionCheck: true,
477
});
478
479
expect(fileUtils.downloadFileFromS3).not.toHaveBeenCalled();
ts/packages/core/test/tools/modifiers.test.ts
+2
-1
@@ -74,6 +74,7 @@ describe('Tools Modifiers', () => {
74
const body = {
75
userId: 'test-user',
76
arguments: { limit: 5 },
77
+ dangerouslySkipVersionCheck: true,
78
};
79
80
const { beforeExecute } = createExecutionModifiers({
@@ -103,7 +104,7 @@ describe('Tools Modifiers', () => {
104
105
it('should apply afterExecute modifier after executing a tool', async () => {
106
const slug = 'COMPOSIO_TOOL';
106
- const body = { userId: 'test-user', arguments: {} };
107
+ const body = { userId: 'test-user', arguments: {}, dangerouslySkipVersionCheck: true };
108
109
const { afterExecute } = createExecutionModifiers({
110
afterModifications: {
ts/packages/core/test/tools/tools.test.ts
+279
-35
@@ -408,6 +408,7 @@ describe('Tools', () => {
408
userId: 'test-user',
409
connectedAccountId: undefined,
410
arguments: { query: 'test' },
411
+ dangerouslySkipVersionCheck: true,
412
};
413
414
await mockToolExecution(context.tools);
@@ -433,6 +434,7 @@ describe('Tools', () => {
434
userId: 'test-user',
435
connectedAccountId: 'test-connected-account-id',
436
arguments: { query: 'test' },
437
+ dangerouslySkipVersionCheck: true,
438
};
439
440
await mockToolExecution(context.tools);
@@ -741,7 +743,7 @@ describe('Tools', () => {
743
it('should pass global version string when configured', async () => {
744
const mockProvider = new MockProvider();
745
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
744
- toolkitVersions: '20250902_00' as any,
746
+ toolkitVersions: '20251201_03' as any,
747
});
748
749
mockClient.tools.list.mockResolvedValueOnce({
@@ -753,7 +755,7 @@ describe('Tools', () => {
755
756
expect(mockClient.tools.list).toHaveBeenCalledWith({
757
toolkit_slug: 'github',
756
- toolkit_versions: '20250902_00',
758
+ toolkit_versions: '20251201_03',
759
});
760
});
761
@@ -761,9 +763,9 @@ describe('Tools', () => {
763
const mockProvider = new MockProvider();
764
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
765
toolkitVersions: {
764
- github: '20250902_00',
766
+ github: '20251201_01',
767
slack: 'latest',
766
- gmail: '20250901_01',
768
+ gmail: '20251201_05',
769
},
770
});
771
@@ -777,9 +779,9 @@ describe('Tools', () => {
779
expect(mockClient.tools.list).toHaveBeenCalledWith({
780
toolkit_slug: 'github',
781
toolkit_versions: {
780
- github: '20250902_00',
782
+ github: '20251201_01',
783
slack: 'latest',
782
- gmail: '20250901_01',
784
+ gmail: '20251201_05',
785
},
786
});
787
});
@@ -788,7 +790,7 @@ describe('Tools', () => {
790
const mockProvider = new MockProvider();
791
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
792
toolkitVersions: {
791
- github: '20250902_00',
793
+ github: '20251201_01',
794
slack: 'latest',
795
},
796
});
@@ -804,7 +806,7 @@ describe('Tools', () => {
806
tool_slugs: 'GITHUB_CREATE_ISSUE,SLACK_SEND_MESSAGE',
807
limit: 9999,
808
toolkit_versions: {
807
- github: '20250902_00',
809
+ github: '20251201_01',
810
slack: 'latest',
811
},
812
});
@@ -846,7 +848,7 @@ describe('Tools', () => {
848
it('should pass global version when retrieving single tool', async () => {
849
const mockProvider = new MockProvider();
850
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
849
- toolkitVersions: '20250902_00' as any,
851
+ toolkitVersions: '20251201_03' as any,
852
});
853
854
mockClient.tools.retrieve.mockResolvedValueOnce(toolMocks.rawTool);
@@ -854,7 +856,7 @@ describe('Tools', () => {
856
await tools.getRawComposioToolBySlug('GITHUB_CREATE_ISSUE');
857
858
expect(mockClient.tools.retrieve).toHaveBeenCalledWith('GITHUB_CREATE_ISSUE', {
857
- toolkit_versions: '20250902_00',
859
+ toolkit_versions: '20251201_03',
860
});
861
});
862
@@ -862,9 +864,9 @@ describe('Tools', () => {
864
const mockProvider = new MockProvider();
865
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
866
toolkitVersions: {
865
- github: '20250902_00',
867
+ github: '20251201_01',
868
slack: 'latest',
867
- gmail: '20250901_01',
869
+ gmail: '20251201_05',
870
},
871
});
872
@@ -874,9 +876,9 @@ describe('Tools', () => {
876
877
expect(mockClient.tools.retrieve).toHaveBeenCalledWith('SLACK_SEND_MESSAGE', {
878
toolkit_versions: {
877
- github: '20250902_00',
879
+ github: '20251201_01',
880
slack: 'latest',
879
- gmail: '20250901_01',
881
+ gmail: '20251201_05',
882
},
883
});
884
});
@@ -890,6 +892,7 @@ describe('Tools', () => {
892
const executeParams: ToolExecuteParams = {
893
arguments: { title: 'Test Issue' },
894
connectedAccountId: 'test-account',
895
+ dangerouslySkipVersionCheck: true, // Required when using 'latest' in manual execution
896
};
897
898
await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
@@ -909,7 +912,7 @@ describe('Tools', () => {
912
it('should use global version when configured', async () => {
913
const mockProvider = new MockProvider();
914
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
912
- toolkitVersions: '20250902_00' as any,
915
+ toolkitVersions: '20251201_03' as any,
916
});
917
const spies = await mockToolExecution(tools);
918
@@ -927,7 +930,7 @@ describe('Tools', () => {
930
custom_connection_data: undefined,
931
arguments: { title: 'Test Issue' },
932
user_id: undefined,
930
- version: '20250902_00', // should use global version
933
+ version: '20251201_03', // should use global version
934
text: undefined,
935
});
936
});
@@ -936,9 +939,9 @@ describe('Tools', () => {
939
const mockProvider = new MockProvider();
940
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
941
toolkitVersions: {
939
- 'test-toolkit': '20250902_00', // Use the actual toolkit slug from mock
942
+ 'test-toolkit': '20251201_01', // Use the actual toolkit slug from mock
943
slack: 'latest',
941
- gmail: '20250901_01',
944
+ gmail: '20251201_05',
945
},
946
});
947
@@ -967,7 +970,7 @@ describe('Tools', () => {
970
custom_connection_data: undefined,
971
arguments: { title: 'Test Issue' },
972
user_id: undefined,
970
- version: '20250902_00', // should use test-toolkit-specific version
973
+ version: '20251201_01', // should use test-toolkit-specific version
974
text: undefined,
975
});
976
});
@@ -976,7 +979,7 @@ describe('Tools', () => {
979
const mockProvider = new MockProvider();
980
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
981
toolkitVersions: {
979
- github: '20250902_00',
982
+ github: '20251201_01',
983
slack: 'latest',
984
},
985
});
@@ -993,6 +996,7 @@ describe('Tools', () => {
996
const executeParams: ToolExecuteParams = {
997
arguments: { title: 'Test Page' },
998
connectedAccountId: 'test-account',
999
+ dangerouslySkipVersionCheck: true, // Required when fallback is 'latest'
1000
};
1001
1002
await tools.execute('NOTION_CREATE_PAGE', executeParams);
@@ -1013,7 +1017,7 @@ describe('Tools', () => {
1017
const mockProvider = new MockProvider();
1018
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1019
toolkitVersions: {
1016
- github: '20250902_00',
1020
+ github: '20251201_01',
1021
slack: 'latest',
1022
},
1023
});
@@ -1023,7 +1027,7 @@ describe('Tools', () => {
1027
const executeParams: ToolExecuteParams = {
1028
arguments: { title: 'Test Issue' },
1029
connectedAccountId: 'test-account',
1026
- version: '20250903_00', // explicit version should override config
1030
+ version: '20251201_03', // explicit version should override config
1031
};
1032
1033
await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
@@ -1035,7 +1039,7 @@ describe('Tools', () => {
1039
custom_connection_data: undefined,
1040
arguments: { title: 'Test Issue' },
1041
user_id: undefined,
1038
- version: '20250903_00', // explicit version takes precedence
1042
+ version: '20251201_03', // explicit version takes precedence
1043
text: undefined,
1044
});
1045
});
@@ -1044,7 +1048,7 @@ describe('Tools', () => {
1048
const mockProvider = new MockProvider();
1049
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1050
toolkitVersions: {
1047
- github: '20250902_00',
1051
+ github: '20251201_01',
1052
},
1053
});
1054
@@ -1062,6 +1066,7 @@ describe('Tools', () => {
1066
const executeParams: ToolExecuteParams = {
1067
arguments: { query: 'test' },
1068
connectedAccountId: 'test-account',
1069
+ dangerouslySkipVersionCheck: true, // Required when toolkit is undefined and version is 'latest'
1070
};
1071
1072
await tools.execute('SOME_CUSTOM_TOOL', executeParams);
@@ -1092,14 +1097,14 @@ describe('Tools', () => {
1097
1098
it('should use environment variable versions when no user config provided', async () => {
1099
// Set environment variables
1095
- process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1100
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20251201_08';
1101
process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1102
1103
const mockProvider = new MockProvider();
1104
// Pass the processed environment variables to the Tools constructor
1105
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1106
toolkitVersions: {
1102
- github: '20250903_00',
1107
+ github: '20251201_08',
1108
slack: 'latest',
1109
},
1110
});
@@ -1114,7 +1119,7 @@ describe('Tools', () => {
1119
expect(mockClient.tools.list).toHaveBeenCalledWith({
1120
toolkit_slug: 'github',
1121
toolkit_versions: {
1117
- github: '20250903_00',
1122
+ github: '20251201_08',
1123
slack: 'latest',
1124
},
1125
});
@@ -1122,14 +1127,14 @@ describe('Tools', () => {
1127
1128
it('should prioritize user config over environment variables', async () => {
1129
// Set environment variables
1125
- process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1130
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20251201_08';
1131
process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1132
1133
const mockProvider = new MockProvider();
1134
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1135
toolkitVersions: {
1131
- github: '20250904_00', // should override env
1132
- gmail: '20250902_00', // new toolkit not in env
1136
+ github: '20251201_04', // should override env
1137
+ gmail: '20251201_05', // new toolkit not in env
1138
},
1139
});
1140
@@ -1143,20 +1148,20 @@ describe('Tools', () => {
1148
expect(mockClient.tools.list).toHaveBeenCalledWith({
1149
toolkit_slug: 'github',
1150
toolkit_versions: {
1146
- github: '20250904_00', // user config wins
1147
- gmail: '20250902_00', // from user config
1151
+ github: '20251201_04', // user config wins
1152
+ gmail: '20251201_05', // from user config
1153
},
1154
});
1155
});
1156
1157
it('should use global version string to override everything', async () => {
1158
// Set environment variables
1154
- process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20250903_00';
1159
+ process.env.COMPOSIO_TOOLKIT_VERSION_GITHUB = '20251201_08';
1160
process.env.COMPOSIO_TOOLKIT_VERSION_SLACK = 'latest';
1161
1162
const mockProvider = new MockProvider();
1163
const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1159
- toolkitVersions: '20250905_00' as any, // global version overrides everything
1164
+ toolkitVersions: '20251201_09' as any, // global version overrides everything
1165
});
1166
1167
mockClient.tools.list.mockResolvedValueOnce({
@@ -1168,7 +1173,246 @@ describe('Tools', () => {
1173
1174
expect(mockClient.tools.list).toHaveBeenCalledWith({
1175
toolkit_slug: 'github',
1171
- toolkit_versions: '20250905_00', // global version ignores env vars
1176
+ toolkit_versions: '20251201_09', // global version ignores env vars
1177
+ });
1178
+ });
1179
+ });
1180
+
1181
+ describe('version check safety for manual execution', () => {
1182
+ it('should throw ComposioToolVersionRequiredError when version is "latest" without dangerouslySkipVersionCheck', async () => {
1183
+ const context = createTestContext();
1184
+ const spies = await mockToolExecution(context.tools);
1185
+
1186
+ const executeParams: ToolExecuteParams = {
1187
+ arguments: { title: 'Test Issue' },
1188
+ connectedAccountId: 'test-account',
1189
+ // dangerouslySkipVersionCheck is not set, should default to false
1190
+ };
1191
+
1192
+ await expect(context.tools.execute('GITHUB_CREATE_ISSUE', executeParams)).rejects.toThrow(
1193
+ 'Toolkit version not specified. For manual execution of the tool please pass a specific toolkit version'
1194
+ );
1195
+ });
1196
+
1197
+ it('should throw ComposioToolVersionRequiredError when version is "latest" with dangerouslySkipVersionCheck set to false', async () => {
1198
+ const context = createTestContext();
1199
+ const spies = await mockToolExecution(context.tools);
1200
+
1201
+ const executeParams: ToolExecuteParams = {
1202
+ arguments: { title: 'Test Issue' },
1203
+ connectedAccountId: 'test-account',
1204
+ dangerouslySkipVersionCheck: false,
1205
+ };
1206
+
1207
+ await expect(context.tools.execute('GITHUB_CREATE_ISSUE', executeParams)).rejects.toThrow(
1208
+ 'Toolkit version not specified. For manual execution of the tool please pass a specific toolkit version'
1209
+ );
1210
+ });
1211
+
1212
+ it('should succeed when version is "latest" with dangerouslySkipVersionCheck set to true', async () => {
1213
+ const context = createTestContext();
1214
+ const spies = await mockToolExecution(context.tools);
1215
+
1216
+ const executeParams: ToolExecuteParams = {
1217
+ arguments: { title: 'Test Issue' },
1218
+ connectedAccountId: 'test-account',
1219
+ dangerouslySkipVersionCheck: true,
1220
+ };
1221
+
1222
+ const result = await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
1223
+
1224
+ expect(result).toEqual(toolMocks.toolExecuteResponse);
1225
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1226
+ allow_tracing: undefined,
1227
+ connected_account_id: 'test-account',
1228
+ custom_auth_params: undefined,
1229
+ custom_connection_data: undefined,
1230
+ arguments: { title: 'Test Issue' },
1231
+ user_id: undefined,
1232
+ version: 'latest',
1233
+ text: undefined,
1234
+ });
1235
+ });
1236
+
1237
+ it('should succeed when executing with a specific version (not "latest") without dangerouslySkipVersionCheck', async () => {
1238
+ const mockProvider = new MockProvider();
1239
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1240
+ toolkitVersions: {
1241
+ 'test-toolkit': '20251201_01',
1242
+ },
1243
+ });
1244
+
1245
+ const testTool = {
1246
+ ...toolMocks.transformedTool,
1247
+ toolkit: { slug: 'test-toolkit', name: 'Test Toolkit' },
1248
+ };
1249
+
1250
+ const spies = await mockToolExecution(tools);
1251
+ spies.getRawComposioToolBySlugSpy.mockReset();
1252
+ spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(testTool as unknown as Tool);
1253
+
1254
+ const executeParams: ToolExecuteParams = {
1255
+ arguments: { title: 'Test Issue' },
1256
+ connectedAccountId: 'test-account',
1257
+ // No dangerouslySkipVersionCheck needed when version is specific
1258
+ };
1259
+
1260
+ const result = await tools.execute('GITHUB_CREATE_ISSUE', executeParams);
1261
+
1262
+ expect(result).toEqual(toolMocks.toolExecuteResponse);
1263
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1264
+ allow_tracing: undefined,
1265
+ connected_account_id: 'test-account',
1266
+ custom_auth_params: undefined,
1267
+ custom_connection_data: undefined,
1268
+ arguments: { title: 'Test Issue' },
1269
+ user_id: undefined,
1270
+ version: '20251201_01', // specific version should work without skip flag
1271
+ text: undefined,
1272
+ });
1273
+ });
1274
+
1275
+ it('should succeed when explicit version parameter overrides "latest" config', async () => {
1276
+ const context = createTestContext();
1277
+ const spies = await mockToolExecution(context.tools);
1278
+
1279
+ const executeParams: ToolExecuteParams = {
1280
+ arguments: { title: 'Test Issue' },
1281
+ connectedAccountId: 'test-account',
1282
+ version: '20251201_03', // explicit version overrides default "latest"
1283
+ // No dangerouslySkipVersionCheck needed
1284
+ };
1285
+
1286
+ const result = await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
1287
+
1288
+ expect(result).toEqual(toolMocks.toolExecuteResponse);
1289
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1290
+ allow_tracing: undefined,
1291
+ connected_account_id: 'test-account',
1292
+ custom_auth_params: undefined,
1293
+ custom_connection_data: undefined,
1294
+ arguments: { title: 'Test Issue' },
1295
+ user_id: undefined,
1296
+ version: '20251201_03',
1297
+ text: undefined,
1298
+ });
1299
+ });
1300
+
1301
+ it('should throw error when explicit version parameter is "latest" without dangerouslySkipVersionCheck', async () => {
1302
+ const mockProvider = new MockProvider();
1303
+ const tools = new Tools(mockClient as unknown as ComposioClient, mockProvider, {
1304
+ toolkitVersions: {
1305
+ 'test-toolkit': '20251201_01', // specific version in config
1306
+ },
1307
+ });
1308
+
1309
+ const testTool = {
1310
+ ...toolMocks.transformedTool,
1311
+ toolkit: { slug: 'test-toolkit', name: 'Test Toolkit' },
1312
+ };
1313
+
1314
+ const spies = await mockToolExecution(tools);
1315
+ spies.getRawComposioToolBySlugSpy.mockReset();
1316
+ spies.getRawComposioToolBySlugSpy.mockResolvedValueOnce(testTool as unknown as Tool);
1317
+
1318
+ const executeParams: ToolExecuteParams = {
1319
+ arguments: { title: 'Test Issue' },
1320
+ connectedAccountId: 'test-account',
1321
+ version: 'latest', // explicit "latest" should still require skip flag
1322
+ };
1323
+
1324
+ await expect(tools.execute('GITHUB_CREATE_ISSUE', executeParams)).rejects.toThrow(
1325
+ 'Toolkit version not specified. For manual execution of the tool please pass a specific toolkit version'
1326
+ );
1327
+ });
1328
+
1329
+ it('should contain appropriate error properties and possible fixes in the cause', async () => {
1330
+ const context = createTestContext();
1331
+ const spies = await mockToolExecution(context.tools);
1332
+
1333
+ const executeParams: ToolExecuteParams = {
1334
+ arguments: { title: 'Test Issue' },
1335
+ connectedAccountId: 'test-account',
1336
+ };
1337
+
1338
+ try {
1339
+ await context.tools.execute('GITHUB_CREATE_ISSUE', executeParams);
1340
+ expect.fail('Should have thrown an error');
1341
+ } catch (error: any) {
1342
+ // The error should be wrapped in ComposioToolExecutionError
1343
+ expect(error).toBeDefined();
1344
+
1345
+ // Check if the error has the right properties, whether wrapped or not
1346
+ if (error.cause) {
1347
+ // If wrapped, check the cause
1348
+ expect(error.cause.code).toContain('TOOL_VERSION_REQUIRED');
1349
+ expect(error.cause.message).toContain('Toolkit version not specified');
1350
+ expect(error.cause.possibleFixes).toBeDefined();
1351
+ expect(error.cause.possibleFixes).toContain(
1352
+ 'Pass the toolkit version as a parameter to the execute function ("latest" is not supported in manual execution)'
1353
+ );
1354
+ } else {
1355
+ // If not wrapped (direct error), check the error itself
1356
+ expect(error.code).toContain('TOOL_VERSION_REQUIRED');
1357
+ expect(error.message).toContain('Toolkit version not specified');
1358
+ expect(error.possibleFixes).toBeDefined();
1359
+ expect(error.possibleFixes).toContain(
1360
+ 'Pass the toolkit version as a parameter to the execute function ("latest" is not supported in manual execution)'
1361
+ );
1362
+ expect(error.possibleFixes).toContain(
1363
+ 'Set the toolkit versions in the Composio config (toolkitVersions: { <toolkit-slug>: "<toolkit-version>" })'
1364
+ );
1365
+ expect(error.possibleFixes).toContain(
1366
+ 'Set the toolkit version in the environment variable (COMPOSIO_TOOLKIT_VERSION_<TOOLKIT_SLUG>)'
1367
+ );
1368
+ expect(error.possibleFixes).toContain(
1369
+ 'Set dangerouslySkipVersionCheck to true (this might cause unexpected behavior when new versions of the tools are released)'
1370
+ );
1371
+ }
1372
+ }
1373
+ });
1374
+
1375
+ it('should allow agentic provider execution with dangerouslySkipVersionCheck in createExecuteToolFn', async () => {
1376
+ const context = createTestContext();
1377
+ const userId = 'test-user';
1378
+
1379
+ // Mock tool retrieval for the get method
1380
+ const getRawComposioToolBySlugSpy = vi.spyOn(context.tools, 'getRawComposioToolBySlug');
1381
+ getRawComposioToolBySlugSpy.mockResolvedValueOnce(
1382
+ toolMocks.transformedTool as unknown as Tool
1383
+ );
1384
+
1385
+ // Mock provider wrapping
1386
+ context.mockProvider.wrapTools.mockImplementation((tools, executeToolFn) => {
1387
+ // Store the execute function so we can test it
1388
+ (context as any).storedExecuteToolFn = executeToolFn;
1389
+ return 'wrapped-tools-collection';
1390
+ });
1391
+
1392
+ // Get the tool (this will internally create the execute tool function)
1393
+ await context.tools.get(userId, 'GITHUB_CREATE_ISSUE');
1394
+
1395
+ // Now call the stored execute function (simulating agentic provider calling it)
1396
+ const storedExecuteToolFn = (context as any).storedExecuteToolFn;
1397
+ expect(storedExecuteToolFn).toBeDefined();
1398
+
1399
+ // Setup mocks for the actual execution
1400
+ const spies = await mockToolExecution(context.tools);
1401
+
1402
+ // Call the execute function that was passed to the provider
1403
+ // This should succeed because createExecuteToolFn sets dangerouslySkipVersionCheck: true
1404
+ const result = await storedExecuteToolFn('GITHUB_CREATE_ISSUE', { title: 'Test Issue' });
1405
+
1406
+ expect(result).toEqual(toolMocks.toolExecuteResponse);
1407
+ expect(mockClient.tools.execute).toHaveBeenCalledWith('COMPOSIO_TOOL', {
1408
+ allow_tracing: undefined,
1409
+ connected_account_id: undefined,
1410
+ custom_auth_params: undefined,
1411
+ custom_connection_data: undefined,
1412
+ arguments: { title: 'Test Issue' },
1413
+ user_id: userId,
1414
+ version: 'latest',
1415
+ text: undefined,
1416
});
1417
});
1418
});
ts/packages/core/test/utils/mocks/provider.mock.ts
+1
-1
@@ -1,7 +1,7 @@
1
import { vi } from 'vitest';
2
import { BaseAgenticProvider } from '../../../src/provider/BaseProvider';
3
4
-export class MockProvider extends BaseAgenticProvider<unknown, unknown> {
4
+export class MockProvider extends BaseAgenticProvider<unknown, unknown, unknown> {
5
readonly name = 'MockProvider';
6
7
wrapTool = vi.fn();