@devries-cameron20 / composio-1 / commits / 59935c023
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.

feat(core): update clients to 2.0.0-rc.12, add `session.executeMeta` (#4842)

## Summary This PR: - updates the owned API clients to `@composio/client@2.0.0-rc.12` and `composio-client==2.0.0rc12` (see https://github.com/ComposioHQ/composio-client/pull/75) - adds `session.executeMeta()` (TypeScript) and `session.execute_meta()` (Python), the one live client endpoint neither SDK wrapped - passes `user_id` to `tools.proxy` as a native client argument in Python, replacing the `extra_body` workaround that was waiting on this release - adds the `ToolRouterSessionMetaToolSlug` type to both SDKs, covering the 9 `COMPOSIO_*` slugs the endpoint accepts `executeMeta` follows each SDK's existing `execute`: same result type (including `resultType` / `result_type`), the input-required error when the tool needs user input, a validation error when the answer has no known result type, and no retries. ```typescript const { data, resultType } = await session.executeMeta('COMPOSIO_SEARCH_TOOLS', { queries: [{ use_case: 'send an email' }], }); ``` ```python result = session.execute_meta( "COMPOSIO_SEARCH_TOOLS", arguments={"queries": [{"use_case": "send an email"}]}, ) ``` Designated PR reviewer: @jkomyno ## Changes - `pnpm-workspace.yaml`, `python/pyproject.toml`, `python/setup.py`: client pins. `pnpm-lock.yaml` and `uv.lock` change only for the client entry. - `ToolRouterSession.executeMeta` / `ToolRouterSession.execute_meta`: forward the slug, arguments and inline custom tool definitions to the meta endpoint. - Python `require_execute_meta_result`: returns the meta answer as the session execute response, with the fields as the client parsed them. - Two changesets: a patch for the client bump and a minor for `executeMeta`, both for `@composio/core` and `@composio/slim`. ## Type of change - [ ] Bug fix - [x] New feature - [x] Refactor/Chore - [ ] Documentation - [ ] Breaking change ## How Has This Been Tested? - `@composio/core`: typecheck, and the full Vitest suite (1804 passed, 2 expected failures). - Typecheck for `@composio/cli` and `@composio/experimental` against rc.12. - Python: full pytest suite (2284 passed, 77 skipped); ruff check and format on the changed files; `uv lock --check`. - New tests cover the request sent to the meta endpoint, the returned result, the input-required error and the unknown `result_type` error in both SDKs. A Python test fails if the local slug list drifts from the client's `execute_meta` signature. - Merged with #4764 locally: no conflicts, core typecheck passes, and the session tests of both SDKs pass on the combined code. ## Checklist - [x] I have read the Code of Conduct and this PR adheres to it - [x] I ran linters/tests locally and they passed - [x] I added tests or explain why not applicable - [x] I added a changeset if this change affects published packages ## Additional context - `session.execute()` already accepts meta tool slugs. `executeMeta` adds a meta-only entry point with a typed slug, not a new capability. - Custom tools named inside a `COMPOSIO_MULTI_EXECUTE_TOOL` call are not run in-process by `executeMeta`, which matches `session.execute()` today. - When arguments are omitted, TypeScript sends `{}` and Python omits the field. Each mirrors its own `execute`. - The other client methods neither SDK wraps are deprecated in the API spec (`tools.retrieveRequiredScopes` and the MCP instance and app methods), so they are left out on purpose. - The Python client's params `TypedDict` for this endpoint lists 7 of the 9 slugs that its method signature accepts.

Alberto Schiabel committed Oct 13, 2026 at 18:19 UTC 59935c02321371b1fc19c9171314ed47a7593769
18 files changed +451 -25
.changeset/owned-client-rc12.md new
+6
@@ -0,0 +1,6 @@
1 +---
2 +'@composio/core': patch
3 +'@composio/slim': patch
4 +---
5 +
6 +Update the owned API client to `@composio/client@2.0.0-rc.12`. OAuth connection data types now accept a `null` `id_token`.
.changeset/session-execute-meta.md new
+8
@@ -0,0 +1,8 @@
1 +---
2 +'@composio/core': minor
3 +'@composio/slim': minor
4 +---
5 +
6 +Add `session.executeMeta()` to run a Composio meta tool (`COMPOSIO_*`) within a session. It takes a meta tool slug and optional arguments, and returns the same result as `session.execute()`, including `resultType`. Like `session.execute()`, it throws `ComposioToolInputRequiredError` when the tool needs user input and is not retried. The new `ToolRouterSessionMetaToolSlug` type lists the accepted slugs.
7 +
8 +The Python SDK gains the matching `session.execute_meta()` and `ToolRouterSessionMetaToolSlug`.
pnpm-lock.yaml
+16 -9
@@ -28,8 +28,8 @@ catalogs:
28 specifier: ^5.20261009.1
29 version: 5.20261009.1
30 '@composio/client':
31 - specifier: 2.0.0-rc.11
32 - version: 2.0.0-rc.11
31 + specifier: 2.0.0-rc.12
32 + version: 2.0.0-rc.12
33 '@effect/language-service':
34 specifier: ^0.87.4
35 version: 0.87.4
@@ -958,7 +958,7 @@ importers:
958 dependencies:
959 '@composio/client':
960 specifier: 'catalog:'
961 - version: 2.0.0-rc.11
961 + version: 2.0.0-rc.12(effect@4.0.3)
962 '@composio/core':
963 specifier: workspace:*
964 version: link:../../packages/core
@@ -1206,7 +1206,7 @@ importers:
1206 version: link:../cli-keyring
1207 '@composio/client':
1208 specifier: 'catalog:'
1209 - version: 2.0.0-rc.11
1209 + version: 2.0.0-rc.12(effect@4.0.3)
1210 '@composio/core':
1211 specifier: workspace:*
1212 version: link:../core
@@ -1312,7 +1312,7 @@ importers:
1312 dependencies:
1313 '@composio/client':
1314 specifier: 'catalog:'
1315 - version: 2.0.0-rc.11
1315 + version: 2.0.0-rc.12(effect@4.0.3)
1316 '@composio/json-schema-to-zod':
1317 specifier: workspace:*
1318 version: link:../json-schema-to-zod
@@ -1717,7 +1717,7 @@ importers:
1717 dependencies:
1718 '@composio/client':
1719 specifier: 'catalog:'
1720 - version: 2.0.0-rc.11
1720 + version: 2.0.0-rc.12(effect@4.0.3)
1721 '@composio/json-schema-to-zod':
1722 specifier: workspace:*
1723 version: link:../json-schema-to-zod
@@ -2279,9 +2279,14 @@ packages:
2279 resolution: {integrity: sha512-ooWCrlZP11i8GImSjTHYHLkvFDP48nS4+204nGb1RiX/WXYHmJA2III9/e2DWVabCESdW7hBAEzHRqUn9OUVvQ==}
2280 engines: {node: '>=0.1.90'}
2281
2282 - '@composio/client@2.0.0-rc.11':
2283 - resolution: {integrity: sha512-jACnskE/mH0dETIBY5C8wpbeszlr1UdPH+y5bCB+CYome2zPVXi41V5bEF+vCDOowOTXhT37y3uyWsezB8gkkw==}
2282 + '@composio/client@2.0.0-rc.12':
2283 + resolution: {integrity: sha512-9LtmqSPweCU6yD9u51gE146indNQcn0ckEGA1SPiexwpNkEm0/1qWN3NEobs661wowDhLsr2i2IYzhpFUhqjEw==}
2284 engines: {node: '>=22'}
2285 + peerDependencies:
2286 + effect: '*'
2287 + peerDependenciesMeta:
2288 + effect:
2289 + optional: true
2290
2291 '@cspotcode/source-map-support@0.8.1':
2292 resolution: {integrity: sha512-IchNf6dN4tHoMFIn/7OE8LWZ19Y6q/67Bmf6vnGREv8RSbBVb9LPJxEcnwrcwX6ixSvaiGoomAUvu4YSxXrVgw==}
@@ -7471,7 +7476,9 @@ snapshots:
7476 '@colors/colors@1.5.0':
7477 optional: true
7478
7474 - '@composio/client@2.0.0-rc.11': {}
7479 + '@composio/client@2.0.0-rc.12(effect@4.0.3)':
7480 + optionalDependencies:
7481 + effect: 4.0.3
7482
7483 '@cspotcode/source-map-support@0.8.1':
7484 dependencies:
pnpm-workspace.yaml
+1 -1
@@ -33,7 +33,7 @@ catalog:
33 '@clack/prompts': '^1.8.1'
34 '@cloudflare/vitest-pool-workers': 0.23.0
35 '@cloudflare/workers-types': ^5.20261009.1
36 - '@composio/client': 2.0.0-rc.11
36 + '@composio/client': 2.0.0-rc.12
37 '@effect/language-service': ^0.87.4
38 '@effect/platform-bun': 4.0.3
39 '@effect/vitest': 4.0.3
python/composio/core/models/__init__.py
+6 -1
@@ -20,7 +20,11 @@ from .logs import Logs
20 from .mcp import MCP
21 from .tool_router import ToolRouter
22 from .tool_router_constants import SESSION_PRESET_DIRECT_TOOLS
23 -from .tool_router_session import ToolRouterSession, ToolRouterSessionExecuteResponse
23 +from .tool_router_session import (
24 + ToolRouterSession,
25 + ToolRouterSessionExecuteResponse,
26 + ToolRouterSessionMetaToolSlug,
27 +)
28 from .tool_router_session_delete import ToolRouterSessionDeleteResponse
29 from .tool_router_session_files import RemoteFile, ToolRouterSessionFilesMount
30 from .toolkits import Toolkits
@@ -70,6 +74,7 @@ __all__ = [
74 "ToolRouterSession",
75 "ToolRouterSessionDeleteResponse",
76 "ToolRouterSessionExecuteResponse",
77 + "ToolRouterSessionMetaToolSlug",
78 "ToolRouterSessionFilesMount",
79 "ToolRouterSessionProxyExecuteResponse",
80 "Toolkits",
python/composio/core/models/inline_custom_tools_payload.py
+11
@@ -5,6 +5,7 @@ import typing as t
5 from composio_client import Omit, omit
6 from composio_client.types.tool_router import (
7 session_attach_params,
8 + session_execute_meta_params,
9 session_execute_params,
10 session_search_params,
11 )
@@ -32,6 +33,16 @@ def inline_custom_tools_execute_experimental(
33 return t.cast(session_execute_params.Experimental, payload)
34
35
36 +def inline_custom_tools_execute_meta_experimental(
37 + payload: t.Optional[InlineCustomToolsWirePayload],
38 +) -> t.Union[session_execute_meta_params.Experimental, Omit]:
39 + if payload is None:
40 + return omit
41 + # Stainless generates endpoint-specific experimental types with the same custom
42 + # definition shape, so this helper centralizes the structural cast.
43 + return t.cast(session_execute_meta_params.Experimental, payload)
44 +
45 +
46 def inline_custom_tools_search_experimental(
47 payload: t.Optional[InlineCustomToolsWirePayload],
48 ) -> t.Union[session_search_params.Experimental, Omit]:
python/composio/core/models/tool_router_session.py
+60
@@ -59,6 +59,7 @@ from composio.core.models.custom_tool_types import (
59 from composio.core.models.experimental import ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT
60 from composio.core.models.inline_custom_tools_payload import (
61 inline_custom_tools_execute_experimental,
62 + inline_custom_tools_execute_meta_experimental,
63 inline_custom_tools_search_experimental,
64 )
65 from composio.core.models.session_context import (
@@ -72,6 +73,7 @@ from composio.core.models.tool_router_session_delete import (
73 from composio.core.models.tools import (
74 ToolExecuteParams,
75 ToolExecutionResponse,
76 + require_execute_meta_result,
77 require_execute_result,
78 )
79 from composio.core.provider import TTool, TToolCollection
@@ -161,6 +163,20 @@ ToolRouterSessionExecuteResponse = SessionExecuteResponse
163 only when the Session sets ``instant.return_instant_charge`` and a charge is
164 available."""
165
166 +ToolRouterSessionMetaToolSlug = t.Literal[
167 + "COMPOSIO_SEARCH_TOOLS",
168 + "COMPOSIO_MULTI_EXECUTE_TOOL",
169 + "COMPOSIO_MANAGE_CONNECTIONS",
170 + "COMPOSIO_WAIT_FOR_CONNECTIONS",
171 + "COMPOSIO_REMOTE_WORKBENCH",
172 + "COMPOSIO_REMOTE_BASH_TOOL",
173 + "COMPOSIO_GET_TOOL_SCHEMAS",
174 + "COMPOSIO_SUBMIT_FEEDBACK",
175 + "COMPOSIO_PROXY_EXECUTE",
176 +]
177 +"""Slug of a Composio meta tool (``COMPOSIO_*``) that
178 +:meth:`ToolRouterSession.execute_meta` can run."""
179 +
180 ToolRouterSessionSearchResponse = session_search_response.SessionSearchResponse
181 """Session search result. A toolkit served by a Composio Instant account
182 lists the covered tools at ``instant_account.allowed_tool_slugs`` on its
@@ -954,6 +970,50 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
970 tool_slug,
971 )
972
973 + def execute_meta(
974 + self,
975 + slug: ToolRouterSessionMetaToolSlug,
976 + *,
977 + arguments: t.Optional[t.Dict[str, t.Any]] = None,
978 + ) -> ToolRouterSessionExecuteResponse:
979 + """
980 + Execute a Composio meta tool (``COMPOSIO_*``) within the session.
981 +
982 + :meth:`execute` also runs meta tools. This method only accepts meta
983 + tool slugs, so a typo is a type error instead of a failed request. The
984 + call is sent to the Composio backend as is: custom tools named in a
985 + ``COMPOSIO_MULTI_EXECUTE_TOOL`` call are not run in-process here.
986 +
987 + :param slug: The meta tool slug to execute.
988 + :param arguments: Optional meta tool arguments.
989 + :returns: The tool execution result, in the same shape as
990 + :meth:`execute`.
991 + :raises ToolInputRequiredError: If the tool needs input from the user
992 + (for example an approval) before it can run. Nothing was executed.
993 + :raises ValidationError: If the API response carries no ``result_type``,
994 + or one this SDK does not know.
995 +
996 + Example:
997 + result = session.execute_meta(
998 + "COMPOSIO_SEARCH_TOOLS",
999 + arguments={"queries": [{"use_case": "send an email"}]},
1000 + )
1001 + print(result.result_type, result.data)
1002 + """
1003 + # Disable retries: a session execution is a non-idempotent write, and a
1004 + # silent retry after a read timeout can duplicate the side effect.
1005 + return require_execute_meta_result(
1006 + self._client.without_retries.tool_router.session.execute_meta(
1007 + session_id=self.session_id,
1008 + slug=slug,
1009 + arguments=arguments if arguments is not None else omit,
1010 + experimental=inline_custom_tools_execute_meta_experimental(
1011 + self._inline_custom_tools_payload
1012 + ),
1013 + ),
1014 + slug,
1015 + )
1016 +
1017 def custom_tools(
1018 self, *, toolkit: t.Optional[str] = None
1019 ) -> t.List[RegisteredCustomTool]:
python/composio/core/models/tools.py
+38 -4
@@ -7,6 +7,10 @@ from pathlib import Path
7
8 import typing_extensions as te
9 from composio_client import APIStatusError, omit
10 +from composio_client.types.tool_router.session_execute_meta_response import (
11 + SessionExecuteMetaInputRequiredResponse,
12 + SessionExecuteMetaResponse,
13 +)
14 from composio_client.types.tool_router.session_execute_response import (
15 SessionExecuteInputRequiredResponse,
16 SessionExecuteResponse,
@@ -130,6 +134,7 @@ def require_executed(
134 response: t.Union[
135 _ExecutedT,
136 SessionExecuteInputRequiredResponse,
137 + SessionExecuteMetaInputRequiredResponse,
138 SessionProxyExecuteInputRequiredResponse,
139 ],
140 subject: str,
@@ -142,7 +147,11 @@ def require_executed(
147 """
148 if not isinstance(
149 response,
145 - (SessionExecuteInputRequiredResponse, SessionProxyExecuteInputRequiredResponse),
150 + (
151 + SessionExecuteInputRequiredResponse,
152 + SessionExecuteMetaInputRequiredResponse,
153 + SessionProxyExecuteInputRequiredResponse,
154 + ),
155 ):
156 return response
157 raise ToolInputRequiredError(
@@ -183,6 +192,33 @@ def require_execute_result(
192 return executed
193
194
195 +def require_execute_meta_result(
196 + response: t.Union[
197 + SessionExecuteMetaResponse, SessionExecuteMetaInputRequiredResponse
198 + ],
199 + slug: str,
200 +) -> SessionExecuteResponse:
201 + """Narrow a session execute_meta response to a meta tool that ran.
202 +
203 + The meta endpoint answers in the same shape as session execute, so the
204 + result is returned as the session execute response and follows the rules of
205 + :func:`require_execute_result`.
206 +
207 + :raises ToolInputRequiredError: If the tool asked for user input instead of
208 + running.
209 + :raises ValidationError: If ``result_type`` is missing or unknown.
210 + """
211 + executed = require_executed(response, f"Tool {slug}")
212 + # Carry the fields over as the client parsed them instead of validating
213 + # them a second time.
214 + return require_execute_result(
215 + SessionExecuteResponse.model_construct(
216 + _fields_set=executed.model_fields_set, **dict(executed)
217 + ),
218 + slug,
219 + )
220 +
221 +
222 def is_execution_successful(result_type: t.Optional[str]) -> bool:
223 """Whether a session tool execution succeeded.
224
@@ -902,9 +938,7 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
938 custom_connection_data=custom_connection_data
939 if custom_connection_data is not None
940 else omit,
905 - # TODO: pass `user_id` natively once composio-client is regenerated
906 - # with it on the proxy endpoint.
907 - extra_body={"user_id": user_id} if user_id is not None else None,
941 + user_id=user_id if user_id is not None else omit,
942 )
943
944
python/pyproject.toml
+1 -1
@@ -7,7 +7,7 @@ requires-python = ">=3.10,<4"
7 dependencies = [
8 "pysher>=1.0.8",
9 "pydantic>=2.11.9",
10 - "composio-client==2.0.0rc11",
10 + "composio-client==2.0.0rc12",
11 "typing-extensions>=4.16.0",
12 "openai>=2.48.0",
13 "json-schema-to-pydantic>=0.4.11",
python/setup.py
+1 -1
@@ -25,7 +25,7 @@ setup(
25 install_requires=[
26 "pysher>=1.0.8",
27 "pydantic>=2.11.9",
28 - "composio-client==2.0.0rc11",
28 + "composio-client==2.0.0rc12",
29 "typing-extensions>=4.16.0",
30 "openai>=2.48.0",
31 "json-schema-to-pydantic>=0.4.11",
python/tests/test_tool_router.py
+94 -1
@@ -33,6 +33,8 @@ from composio.core.models.tool_router import (
33 from composio.core.models.tool_router_session import (
34 DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX,
35 ToolRouterSession,
36 + ToolRouterSessionExecuteResponse,
37 + ToolRouterSessionMetaToolSlug,
38 ToolRouterSessionWithMcp,
39 )
40 from composio.core.models.session_context import SessionContextImpl
@@ -2458,7 +2460,7 @@ def _answering_client(
2460 requests: t.List[httpx.Request] = []
2461
2462 def handler(request: httpx.Request) -> httpx.Response:
2461 - if request.url.path.endswith(("/execute", "/proxy_execute")):
2463 + if request.url.path.endswith(("/execute", "/execute_meta", "/proxy_execute")):
2464 requests.append(request)
2465 return httpx.Response(200, json=body)
2466 return httpx.Response(200, json=_session_json(MCP_SAME_ORIGIN_URL))
@@ -2494,6 +2496,14 @@ class TestExecutionRequiresUserInput:
2496 "Tool GMAIL_SEND_EMAIL",
2497 id="session.execute",
2498 ),
2499 + pytest.param(
2500 + lambda client: _created_session(client).execute_meta(
2501 + "COMPOSIO_MULTI_EXECUTE_TOOL",
2502 + arguments={"tools": [{"tool_slug": "GMAIL_SEND_EMAIL"}]},
2503 + ),
2504 + "Tool COMPOSIO_MULTI_EXECUTE_TOOL",
2505 + id="session.execute_meta",
2506 + ),
2507 pytest.param(
2508 lambda client: _created_session(client).proxy_execute(**_PROXY_PARAMS),
2509 "POST proxy call for toolkit github",
@@ -3351,3 +3361,86 @@ class TestSessionUpdateContract:
3361 "expected_config_version": 8
3362 }
3363 assert reread.config_version == 9
3364 +
3365 +
3366 +class TestSessionExecuteMeta:
3367 + """``session.execute_meta`` runs a Composio meta tool through the meta
3368 + endpoint and answers in the same shape as ``session.execute``.
3369 + """
3370 +
3371 + def test_sends_the_slug_and_arguments_to_the_meta_endpoint(self):
3372 + client, requests = _answering_client(_executed_json("completed", None))
3373 +
3374 + _created_session(client).execute_meta(
3375 + "COMPOSIO_SEARCH_TOOLS",
3376 + arguments={"queries": [{"use_case": "send an email"}]},
3377 + )
3378 +
3379 + assert len(requests) == 1
3380 + assert requests[0].url.path == (
3381 + "/api/v3.1/tool_router/session/session_123/execute_meta"
3382 + )
3383 + assert json.loads(requests[0].content) == {
3384 + "slug": "COMPOSIO_SEARCH_TOOLS",
3385 + "arguments": {"queries": [{"use_case": "send an email"}]},
3386 + }
3387 +
3388 + def test_omits_arguments_when_not_passed(self):
3389 + client, requests = _answering_client(_executed_json("completed", None))
3390 +
3391 + _created_session(client).execute_meta("COMPOSIO_MANAGE_CONNECTIONS")
3392 +
3393 + assert json.loads(requests[0].content) == {
3394 + "slug": "COMPOSIO_MANAGE_CONNECTIONS"
3395 + }
3396 +
3397 + @pytest.mark.parametrize(("result_type", "error", "successful"), _EXECUTED_ANSWERS)
3398 + def test_returns_the_session_execute_response(self, result_type, error, successful):
3399 + client, _ = _answering_client(
3400 + {
3401 + **_executed_json(result_type, error),
3402 + "data": {"results": []},
3403 + "instant_charge": {
3404 + "amount": "0.01",
3405 + "currency": "USD",
3406 + "charged_by": "composio",
3407 + },
3408 + }
3409 + )
3410 +
3411 + result = _created_session(client).execute_meta("COMPOSIO_SEARCH_TOOLS")
3412 +
3413 + assert isinstance(result, ToolRouterSessionExecuteResponse)
3414 + assert result.result_type == result_type
3415 + assert result.error == error
3416 + assert result.data == {"results": []}
3417 + assert result.log_id == "log"
3418 + assert result.instant_charge is not None
3419 + assert result.instant_charge.amount == "0.01"
3420 +
3421 + @pytest.mark.parametrize("body", _INVALID_ANSWERS)
3422 + def test_raises_without_a_known_result_type(self, body):
3423 + client, requests = _answering_client(body)
3424 +
3425 + with pytest.raises(
3426 + ValidationError,
3427 + match="Tool COMPOSIO_SEARCH_TOOLS returned an execute response "
3428 + "without a known result_type",
3429 + ):
3430 + _created_session(client).execute_meta("COMPOSIO_SEARCH_TOOLS")
3431 +
3432 + assert len(requests) == 1
3433 +
3434 + def test_slugs_match_the_generated_client(self):
3435 + from composio_client.resources.tool_router.session import SessionResource
3436 +
3437 + slug_hint = t.get_type_hints(SessionResource.execute_meta)["slug"]
3438 + client_slugs = {
3439 + slug
3440 + for member in t.get_args(slug_hint)
3441 + for slug in t.get_args(member)
3442 + if isinstance(slug, str)
3443 + }
3444 +
3445 + assert client_slugs
3446 + assert set(t.get_args(ToolRouterSessionMetaToolSlug)) == client_slugs
ts/packages/cli/AGENTS.md
+1 -1
@@ -110,7 +110,7 @@ Steps 3–4 (and the TypeScript compiler they need) ship as the `generation-runt
110
111 ### Key Dependencies
112
113 -`effect` (pinned `4.0.3`; `@effect/cli` and `@effect/platform` no longer exist as separate packages — folded into `effect`'s barrel and `effect/{cli,http,process}`), `@effect/platform-bun`, `@effect/vitest` (same exact pin), `@clack/prompts` (terminal UI — stderr by default), `picocolors`, `@composio/client` (owned Composio API client, `2.0.0-rc.11` via the workspace catalog), `@composio/core` (types), `@composio/ts-builders` (AST gen), `@composio/cli-keyring` (OS credential store), `@composio/json-schema-to-effect-schema`, `semver`, `open`, `extract-zip`.
113 +`effect` (pinned `4.0.3`; `@effect/cli` and `@effect/platform` no longer exist as separate packages — folded into `effect`'s barrel and `effect/{cli,http,process}`), `@effect/platform-bun`, `@effect/vitest` (same exact pin), `@clack/prompts` (terminal UI — stderr by default), `picocolors`, `@composio/client` (owned Composio API client, `2.0.0-rc.12` via the workspace catalog), `@composio/core` (types), `@composio/ts-builders` (AST gen), `@composio/cli-keyring` (OS credential store), `@composio/json-schema-to-effect-schema`, `semver`, `open`, `extract-zip`.
114
115 ## Output Conventions: Composable CLI Output
116
ts/packages/core/src/models/ToolRouterSession.ts
+51
@@ -21,6 +21,7 @@ import {
21 ToolRouterSessionExecuteResponseSchema,
22 ToolRouterSessionProxyExecuteResponse,
23 ToolRouterSessionExecuteOptions,
24 + ToolRouterSessionMetaToolSlug,
25 ToolRouterSessionConfig,
26 ToolRouterSessionMetadata,
27 ToolRouterSessionPreloadConfig,
@@ -71,6 +72,7 @@ import type {
72 import { ToolSchema, type Tool, type ToolExecuteResponse } from '../types/tool.types';
73 import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
74 import type {
75 + SessionExecuteMetaParams,
76 SessionExecuteParams,
77 SessionLinkParams,
78 SessionPatchParams,
@@ -742,6 +744,55 @@ export class ToolRouterSession<
744 return ToolRouterSessionExecuteResponseSchema.parse(transformed);
745 }
746
747 + /**
748 + * Execute a Composio meta tool (`COMPOSIO_*`) within the session.
749 + *
750 + * `session.execute()` also runs meta tools. This method only accepts meta
751 + * tool slugs, so a typo is a type error instead of a failed request. The call
752 + * is sent to the Composio backend as is: custom tools named in a
753 + * `COMPOSIO_MULTI_EXECUTE_TOOL` call are not run in-process here.
754 + *
755 + * @param slug - The meta tool slug to execute
756 + * @param arguments_ - Optional meta tool arguments
757 + * @returns The tool execution result, in the same shape as `session.execute()`
758 + * @throws {ComposioToolInputRequiredError} If the tool needs input from the user (for example an approval) before it can run
759 + *
760 + * @example
761 + * ```typescript
762 + * const { data, resultType } = await session.executeMeta('COMPOSIO_SEARCH_TOOLS', {
763 + * queries: [{ use_case: 'send an email' }],
764 + * });
765 + * ```
766 + */
767 + async executeMeta(
768 + slug: ToolRouterSessionMetaToolSlug,
769 + arguments_?: Record<string, unknown>,
770 + requestOptions?: ComposioRequestOptions
771 + ): Promise<ToolRouterSessionExecuteResponse> {
772 + const executeMetaParams: SessionExecuteMetaParams = {
773 + slug,
774 + arguments: arguments_ ?? {},
775 + };
776 + const experimental = inlineCustomToolsExperimental<SessionExecuteMetaParams.Experimental>(
777 + this.inlineCustomToolsPayload
778 + );
779 + if (experimental) {
780 + executeMetaParams.experimental = experimental;
781 + }
782 +
783 + const response = await withCancellation(
784 + () =>
785 + this.client.toolRouter.session.executeMeta(
786 + this.sessionId,
787 + executeMetaParams,
788 + withoutRetries(requestOptions)
789 + ),
790 + requestOptions?.signal
791 + );
792 + const transformed = transformExecuteResponse(response, slug);
793 + return ToolRouterSessionExecuteResponseSchema.parse(transformed);
794 + }
795 +
796 /**
797 * Proxy an API call through Composio's auth layer using the session's connected account.
798 * The backend resolves the connected account from the toolkit within the session.
ts/packages/core/src/types/toolRouter.types.ts
+15
@@ -8,6 +8,7 @@ import { ConnectedAccountExperimentalSchema } from './connectedAccounts.types';
8 import type {
9 SessionConfigHistoryResponse,
10 SessionCreateResponse,
11 + SessionExecuteMetaParams,
12 } from '@composio/client/resources/tool-router/session/session.mjs';
13 import type {
14 CustomTool,
@@ -709,6 +710,18 @@ export interface ToolRouterSessionExecuteOptions {
710 account?: string;
711 }
712
713 +/**
714 + * Slug of a Composio meta tool (`COMPOSIO_*`) that `session.executeMeta()` can
715 + * run, for example `COMPOSIO_SEARCH_TOOLS`.
716 + */
717 +export type ToolRouterSessionMetaToolSlug = SessionExecuteMetaParams['slug'];
718 +
719 +export type ToolRouterSessionExecuteMetaFn = (
720 + slug: ToolRouterSessionMetaToolSlug,
721 + arguments_?: Record<string, unknown>,
722 + requestOptions?: ComposioRequestOptions
723 +) => Promise<ToolRouterSessionExecuteResponse>;
724 +
725 export type ToolRouterSessionPreloadConfig = SessionCreateResponse.Config.Preload;
726
727 export type ToolRouterSessionWorkbenchConfig = SessionCreateResponse.Config.Workbench;
@@ -1137,6 +1150,8 @@ export interface Session<
1150 search: ToolRouterSessionSearchFn;
1151 /** Execute a tool within the session */
1152 execute: ToolRouterSessionExecuteFn;
1153 + /** Execute a Composio meta tool (`COMPOSIO_*`) within the session */
1154 + executeMeta: ToolRouterSessionExecuteMetaFn;
1155 /** Update the session configuration. Mutates this session in-place and resolves to the updated `config`. */
1156 update: ToolRouterSessionUpdateFn;
1157 /** Delete the session. Deleted sessions are no longer retrievable or executable. */
ts/packages/core/test/models/inputRequiredExecution.test.ts
+10 -2
@@ -91,6 +91,14 @@ const executionPaths: Array<{
91 subject: 'Tool GMAIL_SEND_EMAIL',
92 run: client => createSession(client).execute('GMAIL_SEND_EMAIL', { to: 'test@test.com' }),
93 },
94 + {
95 + name: 'session.executeMeta',
96 + subject: 'Tool COMPOSIO_MULTI_EXECUTE_TOOL',
97 + run: client =>
98 + createSession(client).executeMeta('COMPOSIO_MULTI_EXECUTE_TOOL', {
99 + tools: [{ tool_slug: 'GMAIL_SEND_EMAIL', arguments: { to: 'test@test.com' } }],
100 + }),
101 + },
102 {
103 name: 'session.proxyExecute',
104 subject: 'POST proxy call for toolkit github',
@@ -424,14 +432,14 @@ const invalidAnswers = [
432 const executePaths = executionPaths.filter(path => !path.name.includes('proxyExecute'));
433
434 describe.each(invalidAnswers)('session execute answer with $name', ({ body }) => {
427 - it.each(executePaths)('$name raises ValidationError', async ({ run }) => {
435 + it.each(executePaths)('$name raises ValidationError', async ({ run, subject }) => {
436 const { client, fetch } = createClient(body);
437
438 const error = await run(client).catch((caught: unknown) => caught);
439
440 assert(error instanceof ValidationError);
441 expect(error.message).toContain(
434 - 'Tool GMAIL_SEND_EMAIL returned an execute response without a known result_type'
442 + `${subject} returned an execute response without a known result_type`
443 );
444 expect(fetch).toHaveBeenCalledTimes(1);
445 });
ts/packages/core/test/models/toolRouter.test.ts
+101
@@ -60,6 +60,7 @@ const createMockClient = () => ({
60 toolkits: vi.fn(),
61 search: vi.fn(),
62 execute: vi.fn(),
63 + executeMeta: vi.fn(),
64 configHistory: vi.fn(),
65 },
66 },
@@ -3003,6 +3004,106 @@ describe('ToolRouter', () => {
3004 });
3005 });
3006
3007 + describe('executeMeta function', () => {
3008 + const userId = 'user_123';
3009 + const sessionId = 'session_123';
3010 +
3011 + const mockExecuteMetaResponse = {
3012 + result_type: 'completed',
3013 + data: { results: [] },
3014 + error: null,
3015 + log_id: 'log_abc',
3016 + };
3017 +
3018 + it('should call executeMeta with correct params and return camelCase response', async () => {
3019 + mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3020 + mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3021 +
3022 + const session = await toolRouter.create(userId);
3023 + const result = await session.executeMeta('COMPOSIO_SEARCH_TOOLS', {
3024 + queries: [{ use_case: 'send an email' }],
3025 + });
3026 +
3027 + expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3028 + sessionId,
3029 + {
3030 + slug: 'COMPOSIO_SEARCH_TOOLS',
3031 + arguments: { queries: [{ use_case: 'send an email' }] },
3032 + },
3033 + { maxRetries: 0 }
3034 + );
3035 + expect(mockClient.toolRouter.session.execute).not.toHaveBeenCalled();
3036 + expect(result).toEqual({
3037 + data: { results: [] },
3038 + error: null,
3039 + logId: 'log_abc',
3040 + resultType: 'completed',
3041 + });
3042 + });
3043 +
3044 + it('should default arguments to empty object when omitted', async () => {
3045 + mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3046 + mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3047 +
3048 + const session = await toolRouter.create(userId);
3049 + await session.executeMeta('COMPOSIO_MANAGE_CONNECTIONS');
3050 +
3051 + expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3052 + sessionId,
3053 + { slug: 'COMPOSIO_MANAGE_CONNECTIONS', arguments: {} },
3054 + { maxRetries: 0 }
3055 + );
3056 + });
3057 +
3058 + it('should propagate executeMeta API errors', async () => {
3059 + mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3060 + mockClient.toolRouter.session.executeMeta.mockRejectedValueOnce(new Error('Execute failed'));
3061 +
3062 + const session = await toolRouter.create(userId);
3063 +
3064 + await expect(session.executeMeta('COMPOSIO_SEARCH_TOOLS')).rejects.toThrow('Execute failed');
3065 + });
3066 +
3067 + it('should pass inline custom tools to executeMeta when custom tools are bound', async () => {
3068 + const grepTool = createCustomTool('GREP', {
3069 + name: 'Grep',
3070 + description: 'Search local text',
3071 + inputParams: z.object({ pattern: z.string() }),
3072 + execute: vi.fn(async () => ({ matches: [] })),
3073 + });
3074 + mockClient.toolRouter.session.create.mockResolvedValueOnce({
3075 + ...mockSessionCreateResponse,
3076 + experimental: {
3077 + custom_tools: [
3078 + {
3079 + slug: 'LOCAL_GREP',
3080 + original_slug: 'GREP',
3081 + extends_toolkit: null,
3082 + },
3083 + ],
3084 + },
3085 + });
3086 + mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3087 +
3088 + const session = await toolRouter.create(userId, {
3089 + experimental: { customTools: [grepTool] },
3090 + });
3091 + await session.executeMeta('COMPOSIO_SEARCH_TOOLS', { queries: [{ use_case: 'grep' }] });
3092 +
3093 + expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3094 + sessionId,
3095 + {
3096 + slug: 'COMPOSIO_SEARCH_TOOLS',
3097 + arguments: { queries: [{ use_case: 'grep' }] },
3098 + experimental: {
3099 + custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3100 + },
3101 + },
3102 + { maxRetries: 0 }
3103 + );
3104 + });
3105 + });
3106 +
3107 describe('tools function', () => {
3108 const userId = 'user_123';
3109 const sessionId = 'session_123';
ts/packages/core/type-tests/session-execute-meta.test-d.ts new
+27
@@ -0,0 +1,27 @@
1 +/** `session.executeMeta()` is callable on the sessions `create()` and `use()` return. */
2 +import { Composio } from '../src';
3 +import type { ToolRouterSessionExecuteResponse } from '../src';
4 +
5 +declare const composio: Composio;
6 +
7 +async function sessionExecuteMeta(): Promise<void> {
8 + const session = await composio.create('user_123');
9 + const result: ToolRouterSessionExecuteResponse = await session.executeMeta(
10 + 'COMPOSIO_SEARCH_TOOLS',
11 + { queries: [{ use_case: 'send an email' }] }
12 + );
13 + void result;
14 + await session.executeMeta('COMPOSIO_MANAGE_CONNECTIONS');
15 + await session.executeMeta('COMPOSIO_SEARCH_TOOLS', {}, { signal: new AbortController().signal });
16 +
17 + // @ts-expect-error only meta tool slugs are accepted
18 + await session.executeMeta('GMAIL_SEND_EMAIL');
19 +
20 + const withMcp = await composio.create('user_123', { mcp: true });
21 + await withMcp.executeMeta('COMPOSIO_SEARCH_TOOLS');
22 +
23 + const reused = await composio.use('session_123');
24 + await reused.executeMeta('COMPOSIO_SEARCH_TOOLS');
25 +}
26 +
27 +void sessionExecuteMeta;
uv.lock
+4 -4
@@ -820,7 +820,7 @@ dev = [
820
821 [package.metadata]
822 requires-dist = [
823 - { name = "composio-client", specifier = "==2.0.0rc11" },
823 + { name = "composio-client", specifier = "==2.0.0rc12" },
824 { name = "json-schema-to-pydantic", specifier = ">=0.4.11" },
825 { name = "jsonschema", specifier = ">=4.23.0" },
826 { name = "openai", specifier = ">=2.48.0" },
@@ -866,16 +866,16 @@ requires-dist = [
866
867 [[package]]
868 name = "composio-client"
869 -version = "2.0.0rc11"
869 +version = "2.0.0rc12"
870 source = { registry = "https://pypi.org/simple" }
871 dependencies = [
872 { name = "httpx" },
873 { name = "pydantic" },
874 { name = "typing-extensions" },
875 ]
876 -sdist = { url = "https://files.pythonhosted.org/packages/ff/a3/249e8e1e5d089b32b1fae4d876efa7b9b378266ec53f330d94e596edccbe/composio_client-2.0.0rc11.tar.gz", hash = "sha256:b8adb6992a11be5b92755009c13fe3910d20f11cdf07bde6e3e2ec02a6c0644d", size = 611611, upload-time = "2026-10-08T09:11:40.357Z" }
876 +sdist = { url = "https://files.pythonhosted.org/packages/2b/d5/4050dbca38c4b1759bcc0ce35d561c9f6dde688ee71c9555bed5ce6c1386/composio_client-2.0.0rc12.tar.gz", hash = "sha256:3ea962e0ecb9352d24dda9cd6b9f1647ae6cffe097cefbc015837957a141c00d", size = 611837, upload-time = "2026-10-13T12:45:13.777Z" }
877 wheels = [
878 - { url = "https://files.pythonhosted.org/packages/2d/3f/5cc58556d8b5c3278d8c36aa07c136d6d0d268746682d2529f1a425d490c/composio_client-2.0.0rc11-py3-none-any.whl", hash = "sha256:7882126151ad9e1f8a81c673afd90a3c34c703bbece76d7ebbc6dc3d441dafc2", size = 445000, upload-time = "2026-10-08T09:11:38.915Z" },
878 + { url = "https://files.pythonhosted.org/packages/07/5f/8c6cb1e62ad8f7b3d97f02cdd09c5b66521ba0a01021956ceacebd1af615/composio_client-2.0.0rc12-py3-none-any.whl", hash = "sha256:7400b76a62971198c91a8b3a2b49fb97bf1efffa98ec41abce3c1102c4f047da", size = 445175, upload-time = "2026-10-13T12:45:11.814Z" },
879 ]
880
881 [[package]]