@devries-cameron20 / composio Mirror · read-only / commits / 157bf7ba4
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 19:30 UTC

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();