@devries-cameron20 / composio-1 / commits / d66e5ded2
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): accept a boolean proxyExecute shorthand on sessions

jkomyno committed Oct 13, 2026 at 18:26 UTC d66e5ded270073bf71a66141fb5459c1c8621c71
9 files changed +126 -33
.changeset/session-proxy-execute-option.md
+1 -1
@@ -2,4 +2,4 @@
2 '@composio/core': patch
3 ---
4
5 -Add a `proxyExecute` session option. `composio.sessions.create(userId, { proxyExecute: { enable: true } })` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, which lets the agent call a toolkit's API directly with the user's connected account. `session.update()` accepts the same option, and `null` removes the stored value. `enable: false` also turns off the sandbox `proxy_execute()` helper, and the API rejects it at creation together with `sandbox.enableProxyExecution: true`.
5 +Add a `proxyExecute` session option. `composio.sessions.create(userId, { proxyExecute: true })` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool, which lets the agent call a toolkit's API directly with the user's connected account. A boolean is shorthand for `{ enable: boolean }`. `session.update()` accepts the same option, and `null` removes the stored value. `proxyExecute: false` also turns off the sandbox `proxy_execute()` helper, and the API rejects it at creation together with `sandbox.enableProxyExecution: true`.
python/composio/core/models/tool_router.py
+20 -11
@@ -337,6 +337,15 @@ def _preloads_all_custom_tools(
337 return tools == PRELOAD_TOOLS_ALL
338
339
340 +def _proxy_execute_payload(
341 + proxy_execute: t.Union[bool, ToolRouterProxyExecuteConfig],
342 +) -> ToolRouterProxyExecuteConfig:
343 + """Expand the ``proxy_execute`` bool shorthand to the API block."""
344 + if isinstance(proxy_execute, bool):
345 + return {"enable": proxy_execute}
346 + return proxy_execute
347 +
348 +
349 def _apply_session_preset_defaults(
350 session_preset: t.Optional[SessionPreset],
351 manage_connections: t.Optional[t.Union[bool, ToolRouterManageConnectionsConfig]],
@@ -726,7 +735,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
735 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
736 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
737 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
729 - proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
738 + proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
739 preload: t.Optional[ToolRouterPreloadConfig] = None,
740 session_preset: t.Optional[SessionPreset] = None,
741 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -756,7 +765,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
765 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
766 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
767 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
759 - proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
768 + proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
769 preload: t.Optional[ToolRouterPreloadConfig] = None,
770 session_preset: t.Optional[SessionPreset] = None,
771 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -785,7 +794,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
794 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
795 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
796 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
788 - proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
797 + proxy_execute: t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]] = None,
798 preload: t.Optional[ToolRouterPreloadConfig] = None,
799 session_preset: t.Optional[SessionPreset] = None,
800 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -897,13 +906,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
906 it directly from session.tools(); otherwise custom tools
907 remain search-only.
908 Example: {'assistive_prompt': {'user_timezone': 'America/New_York'}}
900 - :param proxy_execute: Optional proxy execute configuration
901 - (ToolRouterProxyExecuteConfig). ``{"enable": True}`` exposes
902 - the ``COMPOSIO_PROXY_EXECUTE`` meta tool. ``{"enable": False}``
903 - also turns off the sandbox ``proxy_execute()`` helper, and the
904 - API rejects it together with
905 - ``sandbox={"enable_proxy_execution": True}``. Leaving it
906 - out keeps the meta tool off.
909 + :param proxy_execute: Optional proxy execute configuration: a bool or
910 + ``ToolRouterProxyExecuteConfig``; ``True`` is shorthand for
911 + ``{"enable": True}``. ``True`` exposes the
912 + ``COMPOSIO_PROXY_EXECUTE`` meta tool. ``False`` also turns off
913 + the sandbox ``proxy_execute()`` helper, and the API rejects it
914 + together with ``sandbox={"enable_proxy_execution": True}``.
915 + Leaving it out keeps the meta tool off.
916 :param instant: Experimental Instant usage policy. The project
917 must allow Instant usage. ``False`` disables it for this
918 Session; a policy can restrict eligible toolkits and tools.
@@ -1103,7 +1112,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1112 if instant is not None:
1113 create_params["instant"] = instant
1114 if proxy_execute is not None:
1106 - create_params["proxy_execute"] = proxy_execute
1115 + create_params["proxy_execute"] = _proxy_execute_payload(proxy_execute)
1116
1117 # Build connections config
1118 connections_config: t.Dict[str, t.Any] = {
python/composio/core/models/tool_router_session.py
+10 -4
@@ -1158,7 +1158,9 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1158 t.Optional[ToolRouterUpdateMultiAccountConfig],
1159 "Omit",
1160 ] = omit,
1161 - proxy_execute: t.Union[t.Optional[ToolRouterProxyExecuteConfig], "Omit"] = omit,
1161 + proxy_execute: t.Union[
1162 + t.Optional[t.Union[bool, ToolRouterProxyExecuteConfig]], "Omit"
1163 + ] = omit,
1164 preload: t.Union[t.Optional[session_patch_params.Preload], "Omit"] = omit,
1165 search: t.Union[t.Optional[session_patch_params.Search], "Omit"] = omit,
1166 execute: t.Union[t.Optional[session_patch_params.Execute], "Omit"] = omit,
@@ -1182,8 +1184,8 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1184 access or an object to set its filters; it does not accept ``None``.
1185 Any object, even one that only sets ``return_instant_charge``,
1186 re-enables Instant usage on a Session set to ``False``.
1185 - ``proxy_execute`` is sent as given: ``{"enable": True}`` exposes the
1186 - ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``{"enable": False}`` also turns
1187 + ``proxy_execute`` takes a bool or ``{"enable": bool}``; ``True``
1188 + exposes the ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``False`` also turns
1189 off the sandbox ``proxy_execute()`` helper, and ``None`` removes the
1190 stored block.
1191
@@ -1277,7 +1279,11 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1279 t.Union[t.Optional[session_patch_params.MultiAccount], "Omit"],
1280 multi_account,
1281 ),
1280 - proxy_execute=proxy_execute,
1282 + proxy_execute=(
1283 + {"enable": proxy_execute}
1284 + if isinstance(proxy_execute, bool)
1285 + else proxy_execute
1286 + ),
1287 preload=t.cast(t.Union[session_patch_params.Preload, "Omit"], preload),
1288 search=t.cast(t.Union[session_patch_params.Search, "Omit"], search),
1289 execute=t.cast(t.Union[session_patch_params.Execute, "Omit"], execute),
python/tests/test_tool_router.py
+24 -7
@@ -185,13 +185,21 @@ class TestToolRouter:
185 # Verify API was called
186 mock_client.tool_router.session.create.assert_called_once()
187
188 - @pytest.mark.parametrize("proxy_execute", [{"enable": True}, {"enable": False}])
189 - def test_create_sends_proxy_execute_as_given(
190 - self, tool_router, mock_client, proxy_execute
188 + @pytest.mark.parametrize(
189 + ("proxy_execute", "expected"),
190 + [
191 + ({"enable": True}, {"enable": True}),
192 + ({"enable": False}, {"enable": False}),
193 + (True, {"enable": True}),
194 + (False, {"enable": False}),
195 + ],
196 + )
197 + def test_create_sends_proxy_execute_block(
198 + self, tool_router, mock_client, proxy_execute, expected
199 ):
200 tool_router.create(user_id="user_123", proxy_execute=proxy_execute)
201 kwargs = mock_client.tool_router.session.create.call_args.kwargs
194 - assert kwargs["proxy_execute"] == proxy_execute
202 + assert kwargs["proxy_execute"] == expected
203
204 def test_create_omits_proxy_execute_by_default(self, tool_router, mock_client):
205 tool_router.create(user_id="user_123")
@@ -3209,12 +3217,21 @@ class TestSessionUpdateContract:
3217 assert session.config_version == 7
3218
3219 @pytest.mark.parametrize(
3212 - "proxy_execute", [{"enable": True}, {"enable": False}, None]
3220 + ("proxy_execute", "expected"),
3221 + [
3222 + ({"enable": True}, {"enable": True}),
3223 + ({"enable": False}, {"enable": False}),
3224 + (True, {"enable": True}),
3225 + (False, {"enable": False}),
3226 + (None, None),
3227 + ],
3228 )
3214 - def test_proxy_execute_is_sent_as_given(self, session, mock_client, proxy_execute):
3229 + def test_proxy_execute_is_sent_as_block(
3230 + self, session, mock_client, proxy_execute, expected
3231 + ):
3232 session.update(proxy_execute=proxy_execute)
3233 kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3217 - assert kwargs["proxy_execute"] == proxy_execute
3234 + assert kwargs["proxy_execute"] == expected
3235
3236 def test_proxy_execute_is_omitted_by_default(self, session, mock_client):
3237 session.update(toolkits={"enable": ["gmail"]})
ts/packages/core/src/lib/toolRouterParams.ts
+11 -1
@@ -18,6 +18,7 @@ import {
18 ToolRouterUpdateExperimentalConfig,
19 ToolRouterSandboxConfig,
20 ToolRouterInstant,
21 + ToolRouterProxyExecute,
22 } from '../types/toolRouter.types';
23 import { ValidationError } from '../errors';
24 import { z } from 'zod';
@@ -203,6 +204,12 @@ export type SessionPatchBody = Omit<
204 expected_config_version?: number;
205 };
206
207 +/** `proxy_execute` as sent on create and update: a boolean becomes `{ enable }`. */
208 +export const transformToolRouterProxyExecuteParams = (
209 + config: ToolRouterProxyExecute
210 +): NonNullable<SessionCreateParams['proxy_execute']> =>
211 + typeof config === 'boolean' ? { enable: config } : config;
212 +
213 export const transformToolRouterInstantParams = (
214 config: ToolRouterInstant
215 ): NonNullable<SessionCreateParams['instant']> => {
@@ -392,7 +399,10 @@ export const transformToolRouterUpdateParams = (
399 }
400 }
401 if (config.proxyExecute !== undefined) {
395 - params.proxy_execute = config.proxyExecute;
402 + params.proxy_execute =
403 + config.proxyExecute === null
404 + ? null
405 + : transformToolRouterProxyExecuteParams(config.proxyExecute);
406 }
407 if (config.preload !== undefined) {
408 params.preload = config.preload;
ts/packages/core/src/models/ToolRouter.ts
+2 -1
@@ -51,6 +51,7 @@ import {
51 transformToolRouterToolkitsParams,
52 transformToolRouterMultiAccountParams,
53 transformToolRouterInstantParams,
54 + transformToolRouterProxyExecuteParams,
55 resolveToolRouterSandboxConfig,
56 } from '../lib/toolRouterParams';
57 import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
@@ -283,7 +284,7 @@ export class ToolRouter<
284 workbench: sandboxPayload,
285 multi_account: multiAccountPayload,
286 ...(routerConfig.proxyExecute !== undefined && {
286 - proxy_execute: routerConfig.proxyExecute,
287 + proxy_execute: transformToolRouterProxyExecuteParams(routerConfig.proxyExecute),
288 }),
289 preload: routerConfig.preload,
290 ...(isDirectToolsPreset && {
ts/packages/core/src/types/toolRouter.types.ts
+17 -5
@@ -251,6 +251,16 @@ export const ToolRouterProxyExecuteConfigSchema = z
251 .strict();
252 export type ToolRouterProxyExecuteConfig = z.infer<typeof ToolRouterProxyExecuteConfigSchema>;
253
254 +/**
255 + * `proxyExecute` as accepted by `sessions.create()` and `session.update()`:
256 + * a boolean is shorthand for `{ enable: boolean }`.
257 + */
258 +export const ToolRouterProxyExecuteSchema = z.union([
259 + z.boolean(),
260 + ToolRouterProxyExecuteConfigSchema,
261 +]);
262 +export type ToolRouterProxyExecute = z.infer<typeof ToolRouterProxyExecuteSchema>;
263 +
264 const ToolRouterCreateSessionConfigBaseSchema = z
265 .object({
266 sessionPreset: z
@@ -337,8 +347,8 @@ const ToolRouterCreateSessionConfigBaseSchema = z
347 .optional()
348 .describe('Multi-account configuration for this session'),
349
340 - proxyExecute: ToolRouterProxyExecuteConfigSchema.optional().describe(
341 - 'Proxy execute configuration for this session. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
350 + proxyExecute: ToolRouterProxyExecuteSchema.optional().describe(
351 + 'Proxy execute configuration for this session; a boolean is shorthand for `{ enable }`. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
352 ),
353
354 preload: z
@@ -462,7 +472,7 @@ export const ToolRouterCreateSessionConfigSchema = z
472 * @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
473 * @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
474 * @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
465 - * @param {object} [proxyExecute] - Proxy execute configuration for this session
475 + * @param {boolean | object} [proxyExecute] - Proxy execute configuration for this session. A boolean is shorthand for `{ enable }`.
476 * @param {boolean} proxyExecute.enable - `true` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool. `false` also turns off the sandbox `proxy_execute()` helper.
477 * @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
478 * @param {string[] | 'all'} [preload.tools] - Tool slugs to preload, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.
@@ -963,9 +973,11 @@ export const ToolRouterUpdateSessionConfigSchema = z
973 .nullable()
974 .optional()
975 .describe('`null` removes the session override; the mode then resolves to disabled'),
966 - proxyExecute: ToolRouterProxyExecuteConfigSchema.nullable()
976 + proxyExecute: ToolRouterProxyExecuteSchema.nullable()
977 .optional()
968 - .describe('Replaces the proxy execute block; `null` removes it'),
978 + .describe(
979 + 'Replaces the proxy execute block; a boolean is shorthand for `{ enable }` and `null` removes it'
980 + ),
981 preload: z
982 .object({
983 tools: z.union([z.array(z.string()), z.literal('all')]).optional(),
ts/packages/core/test/lib/toolRouterParams.test.ts
+7 -1
@@ -194,13 +194,19 @@ describe('transformToolRouterUpdateParams', () => {
194 });
195 });
196
197 - it('maps proxyExecute as given, and null clears it', () => {
197 + it('maps proxyExecute as given, expands a boolean, and null clears it', () => {
198 expect(transformToolRouterUpdateParams({ proxyExecute: { enable: true } })).toEqual({
199 proxy_execute: { enable: true },
200 });
201 expect(transformToolRouterUpdateParams({ proxyExecute: { enable: false } })).toEqual({
202 proxy_execute: { enable: false },
203 });
204 + expect(transformToolRouterUpdateParams({ proxyExecute: true })).toEqual({
205 + proxy_execute: { enable: true },
206 + });
207 + expect(transformToolRouterUpdateParams({ proxyExecute: false })).toEqual({
208 + proxy_execute: { enable: false },
209 + });
210 expect(transformToolRouterUpdateParams({ proxyExecute: null })).toEqual({
211 proxy_execute: null,
212 });
ts/packages/core/test/models/toolRouter.test.ts
+34 -2
@@ -222,17 +222,21 @@ describe('ToolRouter', () => {
222 expect(mockClient.toolRouter.session.create.mock.calls[2]?.[0]).not.toHaveProperty('instant');
223 });
224
225 - it('sends proxyExecute.enable as given and omits the block otherwise', async () => {
225 + it('sends proxyExecute as given, expands the boolean shorthand, and omits the block otherwise', async () => {
226 mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
227
228 await toolRouter.create(userId, { proxyExecute: { enable: true } });
229 await toolRouter.create(userId, { proxyExecute: { enable: false } });
230 + await toolRouter.create(userId, { proxyExecute: true });
231 + await toolRouter.create(userId, { proxyExecute: false });
232 await toolRouter.create(userId);
233
234 const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
235 expect(bodies[0]).toMatchObject({ proxy_execute: { enable: true } });
236 expect(bodies[1]).toMatchObject({ proxy_execute: { enable: false } });
235 - expect(bodies[2]).not.toHaveProperty('proxy_execute');
237 + expect(bodies[2]).toMatchObject({ proxy_execute: { enable: true } });
238 + expect(bodies[3]).toMatchObject({ proxy_execute: { enable: false } });
239 + expect(bodies[4]).not.toHaveProperty('proxy_execute');
240 });
241
242 it('rejects a proxyExecute block without enable', async () => {
@@ -4381,6 +4385,34 @@ describe('ToolRouter', () => {
4385 expect(patchCall().body.manage_connections).toEqual({ callback_url: null });
4386 });
4387
4388 + it('sends proxyExecute as given, expands the boolean shorthand, and null removes the block', async () => {
4389 + const session = await toolRouter.use(sessionId);
4390 +
4391 + await session.update({ proxyExecute: { enable: true } });
4392 + await session.update({ proxyExecute: { enable: false } });
4393 + await session.update({ proxyExecute: true });
4394 + await session.update({ proxyExecute: false });
4395 + await session.update({ proxyExecute: null });
4396 + await session.update({ toolkits: ['gmail'] });
4397 +
4398 + expect(patchCall(0).body.proxy_execute).toEqual({ enable: true });
4399 + expect(patchCall(1).body.proxy_execute).toEqual({ enable: false });
4400 + expect(patchCall(2).body.proxy_execute).toEqual({ enable: true });
4401 + expect(patchCall(3).body.proxy_execute).toEqual({ enable: false });
4402 + expect(patchCall(4).body.proxy_execute).toBeNull();
4403 + expect(patchCall(5).body).not.toHaveProperty('proxy_execute');
4404 + });
4405 +
4406 + it('rejects a proxyExecute block without enable', async () => {
4407 + const session = await toolRouter.use(sessionId);
4408 +
4409 + await expect(
4410 + // @ts-expect-error enable is required
4411 + session.update({ proxyExecute: {} })
4412 + ).rejects.toThrow();
4413 + expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4414 + });
4415 +
4416 it('preserves an empty toolkit allowlist instead of omitting it', async () => {
4417 const session = await toolRouter.use(sessionId);
4418