@devries-cameron20 / composio-1 / commits / 58bcde845
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 proxyExecute on session create and update (PLEN-4324)

Sessions expose the COMPOSIO_PROXY_EXECUTE meta tool only when created with proxy_execute.enable: true, and neither SDK could send that field. Add proxyExecute (TypeScript) and proxy_execute (Python) to sessions.create() and session.update(). The block is passed to the generated client as given and omitted when not set; null on update removes the stored block. enable is required inside the block, matching the API. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

David Tejuosho committed Oct 9, 2026 at 10:55 UTC 58bcde84547113c8460b2548ec542fc207dc6e64
10 files changed +129
.changeset/session-proxy-execute-option.md new
+5
@@ -0,0 +1,5 @@
1 +---
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`.
python/composio/core/models/tool_router.py
+13
@@ -50,6 +50,7 @@ from composio.core.models.tool_router_constants import (
50 )
51 from composio.core.models.tool_router_session import (
52 ToolRouterInstantConfig,
53 + ToolRouterProxyExecuteConfig,
54 ToolRouterSession,
55 ToolRouterSessionConfig,
56 ToolRouterSessionPreloadConfig,
@@ -725,6 +726,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
726 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
727 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
728 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
729 + proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
730 preload: t.Optional[ToolRouterPreloadConfig] = None,
731 session_preset: t.Optional[SessionPreset] = None,
732 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -754,6 +756,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
756 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
757 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
758 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
759 + proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
760 preload: t.Optional[ToolRouterPreloadConfig] = None,
761 session_preset: t.Optional[SessionPreset] = None,
762 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -782,6 +785,7 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
785 sandbox: t.Optional[ToolRouterSandboxConfig] = None,
786 workbench: t.Optional[ToolRouterWorkbenchConfig] = None,
787 multi_account: t.Optional[ToolRouterMultiAccountConfig] = None,
788 + proxy_execute: t.Optional[ToolRouterProxyExecuteConfig] = None,
789 preload: t.Optional[ToolRouterPreloadConfig] = None,
790 session_preset: t.Optional[SessionPreset] = None,
791 experimental: t.Optional[ToolRouterExperimentalConfig] = None,
@@ -893,6 +897,13 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
897 it directly from session.tools(); otherwise custom tools
898 remain search-only.
899 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.
907 :param instant: Experimental Instant usage policy. The project
908 must allow Instant usage. ``False`` disables it for this
909 Session; a policy can restrict eligible toolkits and tools.
@@ -1091,6 +1102,8 @@ class ToolRouter(Resource, t.Generic[TTool, TToolCollection]):
1102 }
1103 if instant is not None:
1104 create_params["instant"] = instant
1105 + if proxy_execute is not None:
1106 + create_params["proxy_execute"] = proxy_execute
1107
1108 # Build connections config
1109 connections_config: t.Dict[str, t.Any] = {
python/composio/core/models/tool_router_session.py
+18
@@ -156,6 +156,18 @@ class ToolRouterInstantConfig(te.TypedDict, total=False):
156 return_instant_charge: bool
157
158
159 +class ToolRouterProxyExecuteConfig(te.TypedDict):
160 + """Proxy execute settings for a Session.
161 +
162 + ``enable=True`` exposes the ``COMPOSIO_PROXY_EXECUTE`` meta tool and
163 + ``enable=False`` also turns off the sandbox ``proxy_execute()`` helper.
164 + Leaving the block out keeps the meta tool off while
165 + ``sandbox.enable_proxy_execution`` controls the helper.
166 + """
167 +
168 + enable: bool
169 +
170 +
171 ToolRouterSessionExecuteResponse = SessionExecuteResponse
172 """Result of :meth:`ToolRouterSession.execute`. ``instant_charge`` is present
173 only when the Session sets ``instant.return_instant_charge`` and a charge is
@@ -1086,6 +1098,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1098 t.Optional[ToolRouterUpdateMultiAccountConfig],
1099 "Omit",
1100 ] = omit,
1101 + proxy_execute: t.Union[t.Optional[ToolRouterProxyExecuteConfig], "Omit"] = omit,
1102 preload: t.Union[t.Optional[session_patch_params.Preload], "Omit"] = omit,
1103 search: t.Union[t.Optional[session_patch_params.Search], "Omit"] = omit,
1104 execute: t.Union[t.Optional[session_patch_params.Execute], "Omit"] = omit,
@@ -1109,6 +1122,10 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1122 access or an object to set its filters; it does not accept ``None``.
1123 Any object, even one that only sets ``return_instant_charge``,
1124 re-enables Instant usage on a Session set to ``False``.
1125 + ``proxy_execute`` is sent as given: ``{"enable": True}`` exposes the
1126 + ``COMPOSIO_PROXY_EXECUTE`` meta tool, ``{"enable": False}`` also turns
1127 + off the sandbox ``proxy_execute()`` helper, and ``None`` removes the
1128 + stored block.
1129
1130 By default the request carries no precondition: the last writer wins.
1131 Pass ``expected_config_version`` (for example this object's
@@ -1200,6 +1217,7 @@ class ToolRouterSession(t.Generic[TTool, TToolCollection]):
1217 t.Union[t.Optional[session_patch_params.MultiAccount], "Omit"],
1218 multi_account,
1219 ),
1220 + proxy_execute=proxy_execute,
1221 preload=t.cast(t.Union[session_patch_params.Preload, "Omit"], preload),
1222 search=t.cast(t.Union[session_patch_params.Search, "Omit"], search),
1223 execute=t.cast(t.Union[session_patch_params.Execute, "Omit"], execute),
python/composio/types.py
+2
@@ -3,6 +3,7 @@ from composio.core.models.connected_accounts import auth_scheme
3 from composio.core.models.experimental import UsageSummaryResponse
4 from composio.core.models.tool_router_session import (
5 ToolRouterInstantConfig,
6 + ToolRouterProxyExecuteConfig,
7 ToolRouterSessionConfig,
8 ToolRouterSessionSearchResponse,
9 )
@@ -28,6 +29,7 @@ __all__ = [
29 "TToolCollection",
30 "InstantCharge",
31 "ToolRouterInstantConfig",
32 + "ToolRouterProxyExecuteConfig",
33 "ToolRouterSessionConfig",
34 "ToolRouterSessionSearchResponse",
35 "ToolExecuteParams",
python/tests/test_tool_router.py
+26
@@ -183,6 +183,19 @@ class TestToolRouter:
183 # Verify API was called
184 mock_client.tool_router.session.create.assert_called_once()
185
186 + @pytest.mark.parametrize("proxy_execute", [{"enable": True}, {"enable": False}])
187 + def test_create_sends_proxy_execute_as_given(
188 + self, tool_router, mock_client, proxy_execute
189 + ):
190 + tool_router.create(user_id="user_123", proxy_execute=proxy_execute)
191 + kwargs = mock_client.tool_router.session.create.call_args.kwargs
192 + assert kwargs["proxy_execute"] == proxy_execute
193 +
194 + def test_create_omits_proxy_execute_by_default(self, tool_router, mock_client):
195 + tool_router.create(user_id="user_123")
196 + kwargs = mock_client.tool_router.session.create.call_args.kwargs
197 + assert "proxy_execute" not in kwargs
198 +
199 def test_create_with_instant_policy(self, tool_router, mock_client):
200 policy = {"toolkits": {"enable": ["exa"]}, "return_instant_charge": True}
201 tool_router.create(user_id="user_123", instant=policy)
@@ -3185,6 +3198,19 @@ class TestSessionUpdateContract:
3198 def test_session_tracks_config_version(self, session):
3199 assert session.config_version == 7
3200
3201 + @pytest.mark.parametrize(
3202 + "proxy_execute", [{"enable": True}, {"enable": False}, None]
3203 + )
3204 + def test_proxy_execute_is_sent_as_given(self, session, mock_client, proxy_execute):
3205 + session.update(proxy_execute=proxy_execute)
3206 + kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3207 + assert kwargs["proxy_execute"] == proxy_execute
3208 +
3209 + def test_proxy_execute_is_omitted_by_default(self, session, mock_client):
3210 + session.update(toolkits={"enable": ["gmail"]})
3211 + kwargs = mock_client.tool_router.session.patch.call_args.kwargs
3212 + assert kwargs["proxy_execute"] is omit
3213 +
3214 def test_instant_policy_is_sent(self, session, mock_client):
3215 session.update(
3216 instant={
ts/packages/core/src/lib/toolRouterParams.ts
+3
@@ -391,6 +391,9 @@ export const transformToolRouterUpdateParams = (
391 params.multi_account = ma;
392 }
393 }
394 + if (config.proxyExecute !== undefined) {
395 + params.proxy_execute = config.proxyExecute;
396 + }
397 if (config.preload !== undefined) {
398 params.preload = config.preload;
399 }
ts/packages/core/src/models/ToolRouter.ts
+3
@@ -282,6 +282,9 @@ export class ToolRouter<
282 ),
283 workbench: sandboxPayload,
284 multi_account: multiAccountPayload,
285 + ...(routerConfig.proxyExecute !== undefined && {
286 + proxy_execute: routerConfig.proxyExecute,
287 + }),
288 preload: routerConfig.preload,
289 ...(isDirectToolsPreset && {
290 search: { enable: false },
ts/packages/core/src/types/toolRouter.types.ts
+26
@@ -233,6 +233,23 @@ export const ToolRouterConfigToolsSchema = z
233 });
234 export type ToolRouterConfigTools = z.infer<typeof ToolRouterConfigToolsSchema>;
235
236 +/**
237 + * Proxy execute settings for a session. `enable: true` exposes the
238 + * `COMPOSIO_PROXY_EXECUTE` meta tool and `enable: false` also turns off the
239 + * sandbox `proxy_execute()` helper. Leaving the block out keeps the meta tool
240 + * off while `sandbox.enableProxyExecution` controls the helper.
241 + */
242 +export const ToolRouterProxyExecuteConfigSchema = z
243 + .object({
244 + enable: z
245 + .boolean()
246 + .describe(
247 + 'true exposes the COMPOSIO_PROXY_EXECUTE meta tool. false also turns off the sandbox proxy_execute() helper.'
248 + ),
249 + })
250 + .strict();
251 +export type ToolRouterProxyExecuteConfig = z.infer<typeof ToolRouterProxyExecuteConfigSchema>;
252 +
253 const ToolRouterCreateSessionConfigBaseSchema = z
254 .object({
255 sessionPreset: z
@@ -319,6 +336,10 @@ const ToolRouterCreateSessionConfigBaseSchema = z
336 .optional()
337 .describe('Multi-account configuration for this session'),
338
339 + proxyExecute: ToolRouterProxyExecuteConfigSchema.optional().describe(
340 + 'Proxy execute configuration for this session. Rejected by the API when enable is false and sandbox.enableProxyExecution is true.'
341 + ),
342 +
343 preload: z
344 .object({
345 tools: z
@@ -440,6 +461,8 @@ export const ToolRouterCreateSessionConfigSchema = z
461 * @param {boolean} [multiAccount.enable] - When true, enables multi-account mode. Falls back to org/project-level config when not set.
462 * @param {number} [multiAccount.maxAccountsPerToolkit] - Max connected accounts per toolkit (2-10, default 5)
463 * @param {boolean} [multiAccount.requireExplicitSelection] - When true, require explicit account selection when multiple accounts are connected
464 + * @param {object} [proxyExecute] - Proxy execute configuration for this session
465 + * @param {boolean} proxyExecute.enable - `true` exposes the `COMPOSIO_PROXY_EXECUTE` meta tool. `false` also turns off the sandbox `proxy_execute()` helper.
466 * @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
467 * @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.
468 * @param {object} [experimental] - Experimental features configuration. Not stable; may change or be removed.
@@ -927,6 +950,9 @@ export const ToolRouterUpdateSessionConfigSchema = z
950 .nullable()
951 .optional()
952 .describe('`null` removes the session override; the mode then resolves to disabled'),
953 + proxyExecute: ToolRouterProxyExecuteConfigSchema.nullable()
954 + .optional()
955 + .describe('Replaces the proxy execute block; `null` removes it'),
956 preload: z
957 .object({
958 tools: z.union([z.array(z.string()), z.literal('all')]).optional(),
ts/packages/core/test/lib/toolRouterParams.test.ts
+12
@@ -194,6 +194,18 @@ describe('transformToolRouterUpdateParams', () => {
194 });
195 });
196
197 + it('maps proxyExecute as given, 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: null })).toEqual({
205 + proxy_execute: null,
206 + });
207 + });
208 +
209 it('keeps an empty toolkit allowlist in the request', () => {
210 expect(transformToolRouterUpdateParams({ toolkits: [] })).toEqual({
211 toolkits: { enable: [] },
ts/packages/core/test/models/toolRouter.test.ts
+21
@@ -221,6 +221,27 @@ describe('ToolRouter', () => {
221 expect(mockClient.toolRouter.session.create.mock.calls[2]?.[0]).not.toHaveProperty('instant');
222 });
223
224 + it('sends proxyExecute.enable as given and omits the block otherwise', async () => {
225 + mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
226 +
227 + await toolRouter.create(userId, { proxyExecute: { enable: true } });
228 + await toolRouter.create(userId, { proxyExecute: { enable: false } });
229 + await toolRouter.create(userId);
230 +
231 + const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
232 + expect(bodies[0]).toMatchObject({ proxy_execute: { enable: true } });
233 + expect(bodies[1]).toMatchObject({ proxy_execute: { enable: false } });
234 + expect(bodies[2]).not.toHaveProperty('proxy_execute');
235 + });
236 +
237 + it('rejects a proxyExecute block without enable', async () => {
238 + await expect(
239 + // @ts-expect-error enable is required
240 + toolRouter.create(userId, { proxyExecute: {} })
241 + ).rejects.toThrow();
242 + expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
243 + });
244 +
245 describe('basic session creation', () => {
246 it('should create a session with minimal configuration', async () => {
247 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);