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

refactor(sdk): share session execution types and result handling (#5256)

This PR: - removes the cast-only inline local-tool payload adapters from both SDKs, letting generated client contracts check each call directly - derives Python's inline payload type from the generated client instead of maintaining a narrower duplicate TypedDict - runs Python `execute_meta()` results through the shared execution normalizer, removing an intermediate model construction and duplicate blocked-result handling - preserves public methods, wire payloads, input-required errors, hook results, charges, cancellation, and retry controls; adds a patch Changeset for the SDK packages ## How Has This Been Tested? - TypeScript core suite: 2,016 passed, with two expected failures; source and public API type checks passed through `bun run turbo run test --filter=@composio/core` and `bun run turbo run typecheck --filter=@composio/core`. - `pnpm --filter @composio/core build`: passed, including package type validation and publint. - `nox -r -s chk tst` in `python/` on Python 3.14.6: Ruff and mypy passed; 2,664 core tests and 39 provider tests passed, with 32 skipped core tests. - Python sdist and wheel builds passed; a smoke check imported the built wheel and normalized a meta-tool result. - Focused TypeScript lint and formatting checks, Python formatting checks, Changeset validation, and `git diff --check` passed. No tests were added or removed: behavior is unchanged, and existing contract tests cover local-tool forwarding, session execution, blocked results, and input requests. Validation is local; live API behavior was not exercised.

Alberto Schiabel committed Nov 9, 2026 at 19:25 UTC 4ee12da92601d854083d447e0a00d07bf660d824
10 files changed +53 -166
.changeset/session-execution-types.md new
+7
@@ -0,0 +1,7 @@
1 +---
2 +'@composio/core': patch
3 +'@composio/slim': patch
4 +'@composio/python-sdk': patch
5 +---
6 +
7 +Use generated client types for inline local-tool payloads and share Python result handling between session tool and meta-tool execution. Public methods and request and response shapes are unchanged.
python/composio/core/models/custom_tool_types.py
+5 -4
@@ -9,7 +9,10 @@ import typing as t
9 from dataclasses import dataclass, field
10
11 import typing_extensions as te
12 -from composio_client.types.tool_router import session_create_params
12 +from composio_client.types.tool_router import (
13 + session_create_params,
14 + session_execute_params,
15 +)
16 from composio_client.types.tool_router.session_execute_response import (
17 SessionExecuteResponse,
18 )
@@ -211,9 +214,7 @@ CustomToolWireDefinition = session_create_params.ExperimentalCustomTool
214 CustomToolkitWireDefinition = session_create_params.ExperimentalCustomToolkit
215
216
214 -class InlineCustomToolsWirePayload(te.TypedDict, total=False):
215 - custom_tools: t.List[CustomToolWireDefinition]
216 - custom_toolkits: t.List[CustomToolkitWireDefinition]
217 +InlineCustomToolsWirePayload = session_execute_params.Experimental
218
219
220 # ────────────────────────────────────────────────────────────────
python/composio/core/models/inline_custom_tools_payload.py deleted
-53
@@ -1,53 +0,0 @@
1 -from __future__ import annotations
2 -
3 -import typing as t
4 -
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 -)
12 -
13 -from composio.core.models.custom_tool_types import InlineCustomToolsWirePayload
14 -
15 -
16 -def inline_custom_tools_attach_experimental(
17 - payload: t.Optional[InlineCustomToolsWirePayload],
18 -) -> t.Union[session_attach_params.Experimental, Omit]:
19 - if payload is None:
20 - return omit
21 - # Stainless generates endpoint-specific experimental types with the same custom
22 - # definition shape, so this helper centralizes the structural cast.
23 - return t.cast(session_attach_params.Experimental, payload)
24 -
25 -
26 -def inline_custom_tools_execute_experimental(
27 - payload: t.Optional[InlineCustomToolsWirePayload],
28 -) -> t.Union[session_execute_params.Experimental, Omit]:
29 - if payload is None:
30 - return omit
31 - # Stainless generates endpoint-specific experimental types with the same custom
32 - # definition shape, so this helper centralizes the structural cast.
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]:
49 - if payload is None:
50 - return omit
51 - # Stainless generates endpoint-specific experimental types with the same custom
52 - # definition shape, so this helper centralizes the structural cast.
53 - return t.cast(session_search_params.Experimental, payload)
python/composio/core/models/session_context.py
+3 -6
@@ -30,9 +30,6 @@ from composio.core.models.custom_tool_types import (
30 ToolRouterSessionProxyExecuteCompleted,
31 ToolRouterSessionProxyExecuteResponse,
32 )
33 -from composio.core.models.inline_custom_tools_payload import (
34 - inline_custom_tools_execute_experimental,
35 -)
33 from composio.core.models.tools import (
34 _serialize_arguments,
35 hook_results_of,
@@ -206,9 +203,9 @@ class SessionContextImpl:
203 session_id=self._session_id,
204 tool_slug=tool_slug,
205 arguments=serialized,
209 - experimental=inline_custom_tools_execute_experimental(
210 - self._inline_custom_tools_payload
211 - ),
206 + experimental=self._inline_custom_tools_payload
207 + if self._inline_custom_tools_payload is not None
208 + else omit,
209 ),
210 tool_slug,
211 )
python/composio/core/models/tool_router.py
+3 -6
@@ -42,9 +42,6 @@ from composio.core.models.custom_tool_types import (
42 InlineCustomToolsWirePayload,
43 LocalTool,
44 )
45 -from composio.core.models.inline_custom_tools_payload import (
46 - inline_custom_tools_attach_experimental,
47 -)
45 from composio.core.models.tool_router_constants import (
46 PRELOAD_TOOLS_ALL,
47 SESSION_PRESET_DIRECT_TOOLS,
@@ -1528,9 +1525,9 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1525 if has_customs:
1526 session = self._client.tool_router.session.attach(
1527 session_id,
1531 - experimental=inline_custom_tools_attach_experimental(
1532 - attach_inline_custom_tools_payload
1533 - ),
1528 + experimental=attach_inline_custom_tools_payload
1529 + if attach_inline_custom_tools_payload is not None
1530 + else omit,
1531 )
1532 else:
1533 session = self._client.tool_router.session.retrieve(session_id)
python/composio/core/models/tool_router_session.py
+10 -16
@@ -58,11 +58,6 @@ from composio.core.models.custom_tool_types import (
58 ToolRouterSessionProxyExecuteResponse,
59 )
60 from composio.core.models.experimental import ACL_ONLY_FOR_SHARED_ERROR_FRAGMENT
61 -from composio.core.models.inline_custom_tools_payload import (
62 - inline_custom_tools_execute_experimental,
63 - inline_custom_tools_execute_meta_experimental,
64 - inline_custom_tools_search_experimental,
65 -)
61 from composio.core.models.session_context import (
62 SessionContextImpl,
63 proxy_execute_impl,
@@ -75,7 +70,6 @@ from composio.core.models.tools import (
70 ToolExecuteParams,
71 ToolExecutionResponse,
72 ToolRouterSessionExecuteResponse,
78 - require_execute_meta_result,
73 require_execute_result,
74 )
75 from composio.core.provider import TTool, TToolCollection
@@ -1007,9 +1001,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1001 session_id=self.session_id,
1002 queries=[{"use_case": query}],
1003 model=model if model else omit,
1010 - experimental=inline_custom_tools_search_experimental(
1011 - self._inline_custom_tools_payload
1012 - ),
1004 + experimental=self._inline_custom_tools_payload
1005 + if self._inline_custom_tools_payload is not None
1006 + else omit,
1007 )
1008
1009 def execute(
@@ -1079,9 +1073,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1073 input_responses if input_responses is not None else omit
1074 ),
1075 request_state=request_state if request_state is not None else omit,
1082 - experimental=inline_custom_tools_execute_experimental(
1083 - self._inline_custom_tools_payload
1084 - ),
1076 + experimental=self._inline_custom_tools_payload
1077 + if self._inline_custom_tools_payload is not None
1078 + else omit,
1079 ),
1080 tool_slug,
1081 )
@@ -1125,7 +1119,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1119 """
1120 # Disable retries: a session execution is a non-idempotent write, and a
1121 # silent retry after a read timeout can duplicate the side effect.
1128 - return require_execute_meta_result(
1122 + return require_execute_result(
1123 self._client.without_retries.tool_router.session.execute_meta(
1124 session_id=self.session_id,
1125 slug=slug,
@@ -1134,9 +1128,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1128 input_responses if input_responses is not None else omit
1129 ),
1130 request_state=request_state if request_state is not None else omit,
1137 - experimental=inline_custom_tools_execute_meta_experimental(
1138 - self._inline_custom_tools_payload
1139 - ),
1131 + experimental=self._inline_custom_tools_payload
1132 + if self._inline_custom_tools_payload is not None
1133 + else omit,
1134 ),
1135 slug,
1136 )
python/composio/core/models/tools.py
+14 -37
@@ -11,6 +11,7 @@ from composio_client.types.tool_router.session_execute_meta_response import (
11 SessionExecuteMetaBlockedResponse,
12 SessionExecuteMetaInputRequiredResponse,
13 SessionExecuteMetaResult,
14 + SessionExecuteMetaResponse,
15 )
16 from composio_client.types.tool_router.session_execute_response import (
17 SessionExecuteBlockedResponse,
@@ -37,9 +38,6 @@ from composio.core.models.custom_tool_types import (
38 InlineCustomToolsWirePayload,
39 ToolRouterHookResult,
40 )
40 -from composio.core.models.inline_custom_tools_payload import (
41 - inline_custom_tools_execute_experimental,
42 -)
41 from composio.core.provider import TTool, TToolCollection
42 from composio.core.provider.agentic import (
43 AgenticProvider,
@@ -245,10 +243,10 @@ def _blocked_execute_result(
243
244
245 def require_execute_result(
248 - response: SessionExecuteResult,
246 + response: t.Union[SessionExecuteResult, SessionExecuteMetaResult],
247 slug: str,
248 ) -> ToolRouterSessionExecuteResponse:
251 - """Narrow a session execute response to a tool that ran.
249 + """Normalize a session execute or execute_meta response to the SDK's result.
250
251 Every session execute response carries a ``result_type``. A ``blocked``
252 call (a session hook blocked it) is returned as a result with empty
@@ -261,9 +259,15 @@ def require_execute_result(
259 running.
260 :raises ValidationError: If ``result_type`` is missing or unknown.
261 """
264 - if isinstance(response, SessionExecuteBlockedResponse):
262 + if isinstance(
263 + response, (SessionExecuteBlockedResponse, SessionExecuteMetaBlockedResponse)
264 + ):
265 return _blocked_execute_result(response)
266 - executed = require_executed(response, f"Tool {slug}")
266 + # The completed client models share a contract but no common typed base.
267 + executed = t.cast(
268 + t.Union[SessionExecuteResponse, SessionExecuteMetaResponse],
269 + require_executed(response, f"Tool {slug}"),
270 + )
271 if executed.result_type not in ("completed", "failed"):
272 raise ValidationError(
273 f"Tool {slug} returned an execute response without a known result_type"
@@ -274,33 +278,6 @@ def require_execute_result(
278 )
279
280
277 -def require_execute_meta_result(
278 - response: SessionExecuteMetaResult,
279 - slug: str,
280 -) -> ToolRouterSessionExecuteResponse:
281 - """Narrow a session execute_meta response to a meta tool that ran.
282 -
283 - The meta endpoint answers in the same shape as session execute, so the
284 - result is returned as the session execute response and follows the rules of
285 - :func:`require_execute_result`.
286 -
287 - :raises ToolInputRequiredError: If the tool asked for user input instead of
288 - running.
289 - :raises ValidationError: If ``result_type`` is missing or unknown.
290 - """
291 - if isinstance(response, SessionExecuteMetaBlockedResponse):
292 - return _blocked_execute_result(response)
293 - executed = require_executed(response, f"Tool {slug}")
294 - # Carry the fields over as the client parsed them instead of validating
295 - # them a second time.
296 - return require_execute_result(
297 - SessionExecuteResponse.model_construct(
298 - _fields_set=executed.model_fields_set, **dict(executed)
299 - ),
300 - slug,
301 - )
302 -
303 -
281 def is_execution_successful(result_type: t.Optional[str]) -> bool:
282 """Whether a session tool execution succeeded.
283
@@ -774,9 +751,9 @@ class Tools(Resource, t.Generic[TTool, TToolCollection]):
751 # Provider-wrapped session tools are agentic calls, so they opt into
752 # direct tool offload when the backend session workbench allows it.
753 enable_auto_workbench_offload=True,
777 - experimental=inline_custom_tools_execute_experimental(
778 - inline_custom_tools_payload
779 - ),
754 + experimental=inline_custom_tools_payload
755 + if inline_custom_tools_payload is not None
756 + else omit,
757 ),
758 slug,
759 )
ts/packages/core/src/models/SessionContext.ts
+2 -6
@@ -28,7 +28,6 @@ import {
28 transformProxyExecuteResponse,
29 } from '../utils/transformers/toolRouterResponseTransform';
30 import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session';
31 -import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
31 import { withCancellation } from '../utils/cancellation';
32 import { withoutRetries } from '../utils/retries';
33
@@ -97,11 +96,8 @@ export class SessionContextImpl implements SessionContext {
96 tool_slug: toolSlug,
97 arguments: arguments_,
98 };
100 - const experimental = inlineCustomToolsExperimental<
101 - NonNullable<SessionExecuteParams['experimental']>
102 - >(this.inlineCustomToolsPayload);
103 - if (experimental) {
104 - executeParams.experimental = experimental;
99 + if (this.inlineCustomToolsPayload) {
100 + executeParams.experimental = this.inlineCustomToolsPayload;
101 }
102
103 const response = await withCancellation(
ts/packages/core/src/models/ToolRouterSession.ts
+9 -21
@@ -78,7 +78,6 @@ import type {
78 SessionLinkParams,
79 SessionPatchParams,
80 SessionPatchResponse,
81 - SessionSearchParams,
81 } from '@composio/client/resources/tool-router/session';
82 import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
83 import { SessionContextImpl } from './SessionContext';
@@ -92,7 +91,6 @@ import {
91 findCustomToolMapEntryByToolkitAndOriginalSlug,
92 } from './CustomTool';
93 import { transformProxyParams } from './proxyParamsTransform';
95 -import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
94 import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';
95 import { parseSessionConfigInput } from '../lib/sessionConfigConflict';
96 import { getSourceSessionConfig } from '../lib/toolRouterSourceSessionConfig';
@@ -681,13 +679,10 @@ export class ToolRouterSession<
679 },
680 requestOptions?: ComposioRequestOptions
681 ): Promise<ToolRouterSessionSearchResponse> {
684 - const experimental = inlineCustomToolsExperimental<
685 - NonNullable<SessionSearchParams['experimental']>
686 - >(this.inlineCustomToolsPayload);
682 const searchParams = {
683 queries: [{ use_case: params.query }],
684 ...(params.toolkits?.length ? { toolkits: params.toolkits } : {}),
690 - ...(experimental ? { experimental } : {}),
685 + ...(this.inlineCustomToolsPayload && { experimental: this.inlineCustomToolsPayload }),
686 };
687 const response = await withCancellation(
688 () => this.client.toolRouter.session.search(this.sessionId, searchParams, requestOptions),
@@ -752,11 +747,8 @@ export class ToolRouterSession<
747 if (options?.account) {
748 executeParams.account = options.account;
749 }
755 - const experimental = inlineCustomToolsExperimental<
756 - NonNullable<SessionExecuteParams['experimental']>
757 - >(this.inlineCustomToolsPayload);
758 - if (experimental) {
759 - executeParams.experimental = experimental;
750 + if (this.inlineCustomToolsPayload) {
751 + executeParams.experimental = this.inlineCustomToolsPayload;
752 }
753
754 const response = await withCancellation(
@@ -804,11 +796,8 @@ export class ToolRouterSession<
796 arguments: arguments_ ?? {},
797 ...inputResponseParams(options),
798 };
807 - const experimental = inlineCustomToolsExperimental<
808 - NonNullable<SessionExecuteMetaParams['experimental']>
809 - >(this.inlineCustomToolsPayload);
810 - if (experimental) {
811 - executeMetaParams.experimental = experimental;
799 + if (this.inlineCustomToolsPayload) {
800 + executeMetaParams.experimental = this.inlineCustomToolsPayload;
801 }
802
803 const response = await withCancellation(
@@ -1025,11 +1014,10 @@ export class ToolRouterSession<
1014 tool?: Tool
1015 ): Promise<ToolExecuteResponse> {
1016 const body = { sessionId: this.sessionId, arguments: input };
1028 - const experimental = inlineCustomToolsExperimental<
1029 - NonNullable<SessionExecuteParams['experimental']>
1030 - >(this.inlineCustomToolsPayload);
1031 - if (experimental) {
1032 - return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool, { experimental });
1017 + if (this.inlineCustomToolsPayload) {
1018 + return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool, {
1019 + experimental: this.inlineCustomToolsPayload,
1020 + });
1021 }
1022 return ToolsModel.executeSessionTool(toolSlug, body, modifiers, tool);
1023 }
ts/packages/core/src/models/inlineCustomToolsPayload.ts deleted
-17
@@ -1,17 +0,0 @@
1 -import type {
2 - SessionExecuteParams,
3 - SessionSearchParams,
4 -} from '@composio/client/resources/tool-router/session';
5 -import type { InlineCustomToolsWirePayload } from '../types/customTool.types';
6 -
7 -type InlineCustomToolsExperimental =
8 - | NonNullable<SessionExecuteParams['experimental']>
9 - | NonNullable<SessionSearchParams['experimental']>;
10 -
11 -export function inlineCustomToolsExperimental<TExperimental extends InlineCustomToolsExperimental>(
12 - payload?: InlineCustomToolsWirePayload
13 -): TExperimental | undefined {
14 - // Stainless generates endpoint-specific experimental types with the same custom
15 - // definition shape, so this helper centralizes the structural cast.
16 - return payload as TExperimental | undefined;
17 -}