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

next
ts 5,003 lines 171 KB
Raw
1 import { describe, it, expect, vi, beforeEach } from 'vitest';
2 import { z } from 'zod/v3';
3 import { ToolRouter } from '../../src/models/ToolRouter';
4 import ComposioClient, {
5 APIError,
6 BadRequestError,
7 ConflictError,
8 NotFoundError,
9 PermissionDeniedError,
10 } from '@composio/client';
11 import { telemetry } from '../../src/telemetry/Telemetry';
12 import { MockProvider } from '../utils/mocks/provider.mock';
13 import { Tools } from '../../src/models/Tools';
14 import { ConnectedAccountStatuses } from '../../src/types/connectedAccounts.types';
15 import {
16 ToolRouterCreateSessionConfig,
17 Session,
18 SessionPreset,
19 type ToolRouterSessionConfig,
20 } from '../../src/types/toolRouter.types';
21 import type { ConnectionRequest } from '../../src/types/connectionRequest.types';
22 import { createCustomTool } from '../../src/models/CustomTool';
23 import { DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX } from '../../src/models/ToolRouterSession';
24 import { ValidationError } from '../../src/errors/ValidationErrors';
25 import { ComposioSessionConfigConflictError } from '../../src/errors/ToolRouterErrors';
26 import { ComposioToolExecutionError } from '../../src/errors/ToolErrors';
27
28 // Mock dependencies
29 vi.mock('../../src/telemetry/Telemetry', () => ({
30 telemetry: {
31 instrument: vi.fn(),
32 },
33 }));
34
35 vi.mock('../../src/models/Tools', () => {
36 return {
37 Tools: vi.fn().mockImplementation(function () {
38 return {
39 getRawComposioTools: vi.fn().mockResolvedValue([{ slug: 'GMAIL_FETCH_EMAILS' }]),
40 getRawToolRouterSessionTools: vi
41 .fn()
42 .mockResolvedValue([{ slug: 'COMPOSIO_SEARCH_TOOLS' }]),
43 wrapToolsForToolRouter: vi.fn().mockReturnValue('mocked-wrapped-tools'),
44 };
45 }),
46 };
47 });
48
49 // Create mock client with ToolRouter-related methods
50 const createMockClient = () => ({
51 baseURL: 'https://api.composio.dev',
52 apiKey: 'test-api-key',
53 post: vi.fn(),
54 toolRouter: {
55 session: {
56 create: vi.fn(),
57 delete: vi.fn(),
58 retrieve: vi.fn(),
59 attach: vi.fn(),
60 patch: vi.fn(),
61 link: vi.fn(),
62 toolkits: vi.fn(),
63 search: vi.fn(),
64 execute: vi.fn(),
65 executeMeta: vi.fn(),
66 configHistory: vi.fn(),
67 },
68 },
69 tools: {
70 list: vi.fn(),
71 retrieve: vi.fn(),
72 execute: vi.fn(),
73 },
74 });
75
76 // Mock response data
77 const mockSessionCreateResponse = {
78 session_id: 'session_123',
79 mcp: {
80 type: 'http',
81 url: 'https://api.composio.dev/api/v3/tool_router/session/session_123',
82 },
83 tool_router_tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE', 'GITHUB_CREATE_ISSUE'],
84 config: {
85 preload: { tools: [] },
86 },
87 config_version: 1,
88 };
89
90 const mockLinkResponse = {
91 connected_account_id: 'conn_456',
92 redirect_url: 'https://composio.dev/auth/redirect',
93 };
94
95 const mockSessionRetrieveResponse = {
96 session_id: 'session_123',
97 mcp: {
98 type: 'http',
99 url: 'https://api.composio.dev/api/v3/tool_router/session/session_123',
100 },
101 tool_router_tools: ['GMAIL_FETCH_EMAILS', 'SLACK_SEND_MESSAGE', 'GITHUB_CREATE_ISSUE'],
102 config: {
103 user_id: 'user_123',
104 toolkits: { enabled: ['gmail', 'slack', 'github'] },
105 auth_configs: {},
106 connected_accounts: {},
107 manage_connections: {
108 enable: true,
109 },
110 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
111 },
112 config_version: 7,
113 };
114
115 const mockToolkitsResponse = {
116 items: [
117 {
118 slug: 'gmail',
119 name: 'Gmail',
120 meta: {
121 logo: 'https://example.com/gmail-logo.png',
122 },
123 is_no_auth: false,
124 connected_account: {
125 id: 'conn_123',
126 status: 'ACTIVE',
127 auth_config: {
128 id: 'auth_config_123',
129 auth_scheme: 'OAUTH2',
130 is_composio_managed: true,
131 },
132 },
133 },
134 {
135 slug: 'slack',
136 name: 'Slack',
137 meta: {
138 logo: 'https://example.com/slack-logo.png',
139 },
140 is_no_auth: false,
141 connected_account: {
142 id: 'conn_456',
143 status: 'INITIATED',
144 auth_config: {
145 id: 'auth_config_456',
146 auth_scheme: 'OAUTH2',
147 is_composio_managed: true,
148 },
149 },
150 },
151 {
152 slug: 'github',
153 name: 'GitHub',
154 meta: {
155 logo: 'https://example.com/github-logo.png',
156 },
157 is_no_auth: false,
158 connected_account: null,
159 },
160 ],
161 next_cursor: 'cursor_789',
162 total_pages: 2,
163 };
164
165 describe('ToolRouter', () => {
166 let toolRouter: ToolRouter<unknown, unknown, MockProvider>;
167 let mockClient: ReturnType<typeof createMockClient>;
168 let mockProvider: MockProvider;
169
170 // Helper function to create expected manage_connections object
171 const createExpectedManageConnections = (
172 overrides: {
173 enable?: boolean;
174 callbackUrl?: string;
175 } = {}
176 ) => ({
177 enable: overrides.enable ?? true,
178 callback_url: overrides.callbackUrl ?? undefined,
179 });
180
181 beforeEach(() => {
182 vi.clearAllMocks();
183 mockClient = createMockClient();
184 mockProvider = new MockProvider();
185 toolRouter = new ToolRouter(mockClient as unknown as ComposioClient, {
186 provider: mockProvider,
187 apiKey: 'test-api-key',
188 });
189 mockClient.toolRouter.session.retrieve.mockResolvedValue(mockSessionRetrieveResponse);
190 mockClient.toolRouter.session.attach.mockResolvedValue(mockSessionRetrieveResponse);
191 });
192
193 describe('constructor', () => {
194 it('should create an instance successfully', () => {
195 expect(toolRouter).toBeInstanceOf(ToolRouter);
196 expect(telemetry.instrument).toHaveBeenCalledWith(toolRouter, 'ToolRouter');
197 });
198
199 it('should store the config reference', () => {
200 expect(toolRouter['config']).toEqual({ provider: mockProvider, apiKey: 'test-api-key' });
201 });
202 });
203
204 describe('create method', () => {
205 const userId = 'user_123';
206
207 it('passes Instant usage only when requested', async () => {
208 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
209 await toolRouter.create(userId, {
210 instant: { toolkits: { enable: ['exa'] }, returnInstantCharge: true },
211 });
212 expect(mockClient.toolRouter.session.create.mock.calls[0]?.[0]).toMatchObject({
213 instant: { toolkits: { enable: ['exa'] }, return_instant_charge: true },
214 });
215
216 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
217 await toolRouter.create(userId, { instant: false });
218 expect(mockClient.toolRouter.session.create.mock.calls[1]?.[0]).toMatchObject({
219 instant: false,
220 });
221
222 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
223 await toolRouter.create(userId);
224 expect(mockClient.toolRouter.session.create.mock.calls[2]?.[0]).not.toHaveProperty('instant');
225 });
226
227 it('sends proxyExecute as given, expands the boolean shorthand, and omits the block otherwise', async () => {
228 mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
229
230 await toolRouter.create(userId, { proxyExecute: { enable: true } });
231 await toolRouter.create(userId, { proxyExecute: { enable: false } });
232 await toolRouter.create(userId, { proxyExecute: true });
233 await toolRouter.create(userId, { proxyExecute: false });
234 await toolRouter.create(userId);
235
236 const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
237 expect(bodies[0]).toMatchObject({ proxy_execute: { enable: true } });
238 expect(bodies[1]).toMatchObject({ proxy_execute: { enable: false } });
239 expect(bodies[2]).toMatchObject({ proxy_execute: { enable: true } });
240 expect(bodies[3]).toMatchObject({ proxy_execute: { enable: false } });
241 expect(bodies[4]).not.toHaveProperty('proxy_execute');
242 });
243
244 it('sends hooks in snake_case, and omits them otherwise', async () => {
245 mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
246
247 await toolRouter.create(userId, {
248 hooks: [
249 {
250 type: 'after_execute',
251 id: 'block_injection',
252 appliesTo: 'all',
253 handler: { type: 'prompt_injection_check', action: 'block' },
254 },
255 ],
256 });
257 await toolRouter.create(userId);
258
259 const bodies = mockClient.toolRouter.session.create.mock.calls.map(call => call[0]);
260 expect(bodies[0]).toMatchObject({
261 hooks: [
262 {
263 type: 'after_execute',
264 id: 'block_injection',
265 applies_to: 'all',
266 handler: { type: 'prompt_injection_check', action: 'block' },
267 },
268 ],
269 });
270 expect(bodies[1]).not.toHaveProperty('hooks');
271 });
272
273 it('rejects a prompt injection check on a before_execute hook, as the API does', async () => {
274 await expect(
275 toolRouter.create(userId, {
276 hooks: [
277 {
278 type: 'before_execute',
279 id: 'block_injection',
280 appliesTo: 'all',
281 // @ts-expect-error a before_execute hook only takes a condition_check handler
282 handler: { type: 'prompt_injection_check', action: 'block' },
283 },
284 ],
285 })
286 ).rejects.toThrow();
287 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
288 });
289
290 it('rejects hooks together with a saved session config', async () => {
291 await expect(
292 toolRouter.create(
293 userId,
294 // @ts-expect-error hooks cannot be combined with sessionConfigId
295 {
296 hooks: [
297 {
298 type: 'after_execute',
299 id: 'block_injection',
300 appliesTo: 'all',
301 handler: { type: 'prompt_injection_check', action: 'block' },
302 },
303 ],
304 experimental: { sessionConfigId: 'sc_1' },
305 }
306 )
307 ).rejects.toThrow();
308 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
309 });
310
311 it('rejects a proxyExecute block without enable', async () => {
312 await expect(
313 // @ts-expect-error enable is required
314 toolRouter.create(userId, { proxyExecute: {} })
315 ).rejects.toThrow();
316 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
317 });
318
319 describe('basic session creation', () => {
320 it('should create a session with minimal configuration', async () => {
321 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
322
323 const session = await toolRouter.create(userId);
324
325 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
326 {
327 user_id: userId,
328 toolkits: undefined,
329 auth_configs: undefined,
330 connected_accounts: undefined,
331 tools: undefined,
332 tags: undefined,
333 manage_connections: createExpectedManageConnections(),
334 workbench: undefined,
335 },
336 undefined
337 );
338
339 expect(session).toHaveProperty('sessionId', 'session_123');
340 expect(session).toHaveProperty('mcp');
341 expect(session.mcp).toEqual({
342 type: 'http',
343 url: 'https://api.composio.dev/api/v3/tool_router/session/session_123',
344 headers: {
345 'x-api-key': 'test-api-key',
346 },
347 });
348 expect(session).toHaveProperty('tools');
349 expect(session).toHaveProperty('authorize');
350 expect(session).toHaveProperty('toolkits');
351 });
352
353 it('should create a session with empty config object', async () => {
354 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
355
356 const session = await toolRouter.create(userId, {});
357
358 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
359 {
360 user_id: userId,
361 toolkits: undefined,
362 auth_configs: undefined,
363 connected_accounts: undefined,
364 tools: undefined,
365 tags: undefined,
366 manage_connections: createExpectedManageConnections(),
367 workbench: undefined,
368 },
369 undefined
370 );
371
372 expect(session.sessionId).toBe('session_123');
373 expect(session.preload.tools).toEqual([]);
374 expect(session.configVersion).toBe(1);
375 expect(session.config).toEqual(mockSessionCreateResponse.config);
376 });
377
378 it('should create a session with preloaded tools', async () => {
379 mockClient.toolRouter.session.create.mockResolvedValueOnce({
380 ...mockSessionCreateResponse,
381 config: {
382 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
383 },
384 config_version: 2,
385 });
386
387 const session = await toolRouter.create(userId, {
388 toolkits: ['gmail'],
389 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
390 });
391
392 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
393 {
394 user_id: userId,
395 toolkits: {
396 enable: ['gmail'],
397 },
398 auth_configs: undefined,
399 connected_accounts: undefined,
400 tools: undefined,
401 tags: undefined,
402 manage_connections: createExpectedManageConnections(),
403 workbench: undefined,
404 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
405 },
406 undefined
407 );
408
409 expect(session.preload.tools).toEqual(['GMAIL_FETCH_EMAILS']);
410 expect(session.configVersion).toBe(2);
411 });
412
413 it('should create a session with preload all', async () => {
414 mockClient.toolRouter.session.create.mockResolvedValueOnce({
415 ...mockSessionCreateResponse,
416 config: {
417 preload: { tools: 'all' },
418 },
419 config_version: 2,
420 });
421
422 const session = await toolRouter.create(userId, {
423 toolkits: ['github'],
424 preload: { tools: 'all' },
425 });
426
427 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
428 {
429 user_id: userId,
430 toolkits: {
431 enable: ['github'],
432 },
433 auth_configs: undefined,
434 connected_accounts: undefined,
435 tools: undefined,
436 tags: undefined,
437 manage_connections: createExpectedManageConnections(),
438 workbench: undefined,
439 preload: { tools: 'all' },
440 },
441 undefined
442 );
443
444 expect(session.preload.tools).toBe('all');
445 });
446
447 it('should reject custom tool slugs in top-level preload', async () => {
448 const grepTool = createCustomTool('GREP', {
449 name: 'Grep',
450 description: 'Search local text',
451 inputParams: z.object({ pattern: z.string() }),
452 execute: vi.fn(async () => ({ matches: [] })),
453 });
454
455 await expect(
456 toolRouter.create(userId, {
457 preload: { tools: ['GREP'] },
458 experimental: { customTools: [grepTool] },
459 })
460 ).rejects.toThrow('Set preload: true on the SDK custom tool');
461 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
462 });
463
464 it('should apply the direct_tools session preset defaults', async () => {
465 mockClient.toolRouter.session.create.mockResolvedValueOnce({
466 ...mockSessionCreateResponse,
467 config: {
468 preload: { tools: 'all' },
469 },
470 });
471
472 const session = await toolRouter.create(userId, {
473 sessionPreset: SessionPreset.DIRECT_TOOLS,
474 toolkits: ['github'],
475 });
476
477 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
478 {
479 user_id: userId,
480 toolkits: {
481 enable: ['github'],
482 },
483 auth_configs: undefined,
484 connected_accounts: undefined,
485 tools: undefined,
486 tags: undefined,
487 manage_connections: { enable: false },
488 workbench: { enable: false },
489 multi_account: undefined,
490 preload: { tools: 'all' },
491 search: { enable: false },
492 execute: { enable_multi_execute: false },
493 experimental: undefined,
494 },
495 undefined
496 );
497 expect(session.preload.tools).toBe('all');
498 });
499
500 it('should respect explicit overrides with the direct_tools session preset', async () => {
501 mockClient.toolRouter.session.create.mockResolvedValueOnce({
502 ...mockSessionCreateResponse,
503 config: {
504 preload: { tools: ['GITHUB_CREATE_ISSUE'] },
505 },
506 });
507
508 const session = await toolRouter.create(userId, {
509 sessionPreset: SessionPreset.DIRECT_TOOLS,
510 toolkits: ['github'],
511 manageConnections: true,
512 workbench: { enable: true },
513 preload: { tools: ['GITHUB_CREATE_ISSUE'] },
514 });
515
516 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
517 {
518 user_id: userId,
519 toolkits: {
520 enable: ['github'],
521 },
522 auth_configs: undefined,
523 connected_accounts: undefined,
524 tools: undefined,
525 tags: undefined,
526 manage_connections: { enable: true },
527 workbench: { enable: true },
528 multi_account: undefined,
529 preload: { tools: ['GITHUB_CREATE_ISSUE'] },
530 search: { enable: false },
531 execute: { enable_multi_execute: false },
532 experimental: undefined,
533 },
534 undefined
535 );
536 expect(session.preload.tools).toEqual(['GITHUB_CREATE_ISSUE']);
537 });
538
539 it('should not apply direct_tools custom preload default when preload is explicitly overridden', async () => {
540 const grepTool = createCustomTool('GREP', {
541 name: 'Grep',
542 description: 'Search local text',
543 inputParams: z.object({ pattern: z.string() }),
544 execute: vi.fn(async () => ({ matches: [] })),
545 });
546
547 mockClient.toolRouter.session.create.mockResolvedValueOnce({
548 ...mockSessionCreateResponse,
549 config: {
550 preload: { tools: ['GITHUB_CREATE_ISSUE'] },
551 },
552 experimental: {
553 custom_tools: [
554 {
555 slug: 'SERVER_GREP',
556 original_slug: 'GREP',
557 extends_toolkit: null,
558 },
559 ],
560 },
561 });
562
563 await toolRouter.create(userId, {
564 sessionPreset: SessionPreset.DIRECT_TOOLS,
565 toolkits: ['github'],
566 preload: { tools: ['GITHUB_CREATE_ISSUE'] },
567 experimental: { customTools: [grepTool] },
568 });
569
570 const payload = mockClient.toolRouter.session.create.mock.calls[0][0];
571 expect(payload.preload).toEqual({ tools: ['GITHUB_CREATE_ISSUE'] });
572 expect(payload.experimental?.custom_tools?.[0]).not.toHaveProperty('preload');
573 });
574
575 it('should create a session with user ID only and verify MCP type transformation', async () => {
576 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
577
578 const session = await toolRouter.create(userId);
579
580 expect(session.mcp.type).toBe('http');
581 expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
582 });
583 });
584
585 describe('toolkits configuration', () => {
586 it('should create a session with toolkits as array (enable toolkits)', async () => {
587 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
588
589 const config: ToolRouterCreateSessionConfig = {
590 toolkits: ['gmail', 'slack', 'github'],
591 };
592
593 await toolRouter.create(userId, config);
594
595 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
596 {
597 user_id: userId,
598 toolkits: {
599 enable: ['gmail', 'slack', 'github'],
600 },
601 auth_configs: undefined,
602 connected_accounts: undefined,
603 tools: undefined,
604 tags: undefined,
605 manage_connections: createExpectedManageConnections(),
606 workbench: undefined,
607 },
608 undefined
609 );
610 });
611
612 it('should create a session with enable toolkits configuration', async () => {
613 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
614
615 const config: ToolRouterCreateSessionConfig = {
616 toolkits: {
617 enable: ['gmail', 'slack'],
618 },
619 };
620
621 await toolRouter.create(userId, config);
622
623 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
624 {
625 user_id: userId,
626 toolkits: {
627 enable: ['gmail', 'slack'],
628 },
629 auth_configs: undefined,
630 connected_accounts: undefined,
631 tools: undefined,
632 tags: undefined,
633 manage_connections: createExpectedManageConnections(),
634 workbench: undefined,
635 },
636 undefined
637 );
638 });
639
640 it('should create a session with disable toolkits configuration', async () => {
641 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
642
643 const config: ToolRouterCreateSessionConfig = {
644 toolkits: {
645 disable: ['notion', 'trello'],
646 },
647 };
648
649 await toolRouter.create(userId, config);
650
651 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
652 {
653 user_id: userId,
654 toolkits: {
655 disable: ['notion', 'trello'],
656 },
657 auth_configs: undefined,
658 connected_accounts: undefined,
659 tools: undefined,
660 tags: undefined,
661 manage_connections: createExpectedManageConnections(),
662 workbench: undefined,
663 },
664 undefined
665 );
666 });
667 });
668
669 describe('tags configuration', () => {
670 it('should create a session with tags as array', async () => {
671 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
672
673 const config: ToolRouterCreateSessionConfig = {
674 tags: ['readOnlyHint', 'idempotentHint'],
675 };
676
677 await toolRouter.create(userId, config);
678
679 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
680 {
681 user_id: userId,
682 toolkits: undefined,
683 auth_configs: undefined,
684 connected_accounts: undefined,
685 tools: undefined,
686 tags: {
687 enable: ['readOnlyHint', 'idempotentHint'],
688 },
689 manage_connections: createExpectedManageConnections(),
690 workbench: undefined,
691 },
692 undefined
693 );
694 });
695
696 it('should create a session with tags object with enable property', async () => {
697 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
698
699 const config: ToolRouterCreateSessionConfig = {
700 tags: {
701 enable: ['readOnlyHint', 'idempotentHint'],
702 },
703 };
704
705 await toolRouter.create(userId, config);
706
707 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
708 {
709 user_id: userId,
710 toolkits: undefined,
711 auth_configs: undefined,
712 connected_accounts: undefined,
713 tools: undefined,
714 tags: {
715 enable: ['readOnlyHint', 'idempotentHint'],
716 },
717 manage_connections: createExpectedManageConnections(),
718 workbench: undefined,
719 },
720 undefined
721 );
722 });
723
724 it('should create a session with tags object with disable property', async () => {
725 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
726
727 const config: ToolRouterCreateSessionConfig = {
728 tags: {
729 disable: ['destructiveHint'],
730 },
731 };
732
733 await toolRouter.create(userId, config);
734
735 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
736 {
737 user_id: userId,
738 toolkits: undefined,
739 auth_configs: undefined,
740 connected_accounts: undefined,
741 tools: undefined,
742 tags: {
743 enable: undefined,
744 disable: ['destructiveHint'],
745 },
746 manage_connections: createExpectedManageConnections(),
747 workbench: undefined,
748 },
749 undefined
750 );
751 });
752
753 it('should create a session with tags object with both enable and disable properties', async () => {
754 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
755
756 const config: ToolRouterCreateSessionConfig = {
757 tags: {
758 enable: ['readOnlyHint', 'idempotentHint'],
759 disable: ['destructiveHint'],
760 },
761 };
762
763 await toolRouter.create(userId, config);
764
765 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
766 {
767 user_id: userId,
768 toolkits: undefined,
769 auth_configs: undefined,
770 connected_accounts: undefined,
771 tools: undefined,
772 tags: {
773 enable: ['readOnlyHint', 'idempotentHint'],
774 disable: ['destructiveHint'],
775 },
776 manage_connections: createExpectedManageConnections(),
777 workbench: undefined,
778 },
779 undefined
780 );
781 });
782
783 it('should create a session with single tag in array', async () => {
784 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
785
786 const config: ToolRouterCreateSessionConfig = {
787 tags: ['readOnlyHint'],
788 };
789
790 await toolRouter.create(userId, config);
791
792 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
793 {
794 user_id: userId,
795 toolkits: undefined,
796 auth_configs: undefined,
797 connected_accounts: undefined,
798 tools: undefined,
799 tags: {
800 enable: ['readOnlyHint'],
801 },
802 manage_connections: createExpectedManageConnections(),
803 workbench: undefined,
804 },
805 undefined
806 );
807 });
808
809 it('should create a session with all tag types', async () => {
810 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
811
812 const config: ToolRouterCreateSessionConfig = {
813 tags: ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'],
814 };
815
816 await toolRouter.create(userId, config);
817
818 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
819 {
820 user_id: userId,
821 toolkits: undefined,
822 auth_configs: undefined,
823 connected_accounts: undefined,
824 tools: undefined,
825 tags: {
826 enable: ['readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'],
827 },
828 manage_connections: createExpectedManageConnections(),
829 workbench: undefined,
830 },
831 undefined
832 );
833 });
834
835 it('should create a session with tags combined with toolkits', async () => {
836 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
837
838 const config: ToolRouterCreateSessionConfig = {
839 toolkits: ['gmail', 'slack'],
840 tags: ['readOnlyHint'],
841 };
842
843 await toolRouter.create(userId, config);
844
845 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
846 {
847 user_id: userId,
848 toolkits: {
849 enable: ['gmail', 'slack'],
850 },
851 auth_configs: undefined,
852 connected_accounts: undefined,
853 tools: undefined,
854 tags: {
855 enable: ['readOnlyHint'],
856 },
857 manage_connections: createExpectedManageConnections(),
858 workbench: undefined,
859 },
860 undefined
861 );
862 });
863 });
864
865 // describe('tools configuration', () => {
866 // it('should create a session with tools overrides as array', async () => {
867 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
868
869 // const config: ToolRouterCreateSessionConfig = {
870 // tools: {
871 // overrides: {
872 // gmail: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'],
873 // },
874 // },
875 // };
876
877 // await toolRouter.create(userId, config);
878
879 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
880 // user_id: userId,
881 // toolkits: undefined,
882 // auth_configs: undefined,
883 // connected_accounts: undefined,
884 // tools: {
885 // overrides: {
886 // gmail: { enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'] },
887 // },
888 // filters: undefined,
889 // },
890 // connections: createExpectedConnections(),
891 // execution: undefined,
892 // });
893 // });
894
895 // it('should create a session with tools overrides with enable tools', async () => {
896 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
897
898 // const config: ToolRouterCreateSessionConfig = {
899 // tools: {
900 // overrides: {
901 // gmail: { enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'] },
902 // },
903 // },
904 // };
905
906 // await toolRouter.create(userId, config);
907
908 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
909 // user_id: userId,
910 // toolkits: undefined,
911 // auth_configs: undefined,
912 // connected_accounts: undefined,
913 // tools: {
914 // overrides: {
915 // gmail: { enable: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'] },
916 // },
917 // filters: undefined,
918 // },
919 // connections: createExpectedConnections(),
920 // execution: undefined,
921 // });
922 // });
923
924 // it('should create a session with tools overrides with disable tools', async () => {
925 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
926
927 // const config: ToolRouterCreateSessionConfig = {
928 // tools: {
929 // overrides: {
930 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
931 // },
932 // },
933 // };
934
935 // await toolRouter.create(userId, config);
936
937 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
938 // user_id: userId,
939 // toolkits: undefined,
940 // auth_configs: undefined,
941 // connected_accounts: undefined,
942 // tools: {
943 // overrides: {
944 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
945 // },
946 // filters: undefined,
947 // },
948 // connections: createExpectedConnections(),
949 // execution: undefined,
950 // });
951 // });
952
953 // it('should create a session with tag filters as array', async () => {
954 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
955
956 // const config: ToolRouterCreateSessionConfig = {
957 // tools: {
958 // tags: ['important', 'email'],
959 // },
960 // };
961
962 // await toolRouter.create(userId, config);
963
964 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
965 // user_id: userId,
966 // toolkits: undefined,
967 // auth_configs: undefined,
968 // connected_accounts: undefined,
969 // tools: {
970 // overrides: undefined,
971 // filters: {
972 // tags: { include: ['important', 'email'] },
973 // },
974 // },
975 // connections: createExpectedConnections(),
976 // execution: undefined,
977 // });
978 // });
979
980 // it('should create a session with enable tag filters', async () => {
981 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
982
983 // const config: ToolRouterCreateSessionConfig = {
984 // tools: {
985 // tags: { enable: ['important', 'email'] },
986 // },
987 // };
988
989 // await toolRouter.create(userId, config);
990
991 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
992 // user_id: userId,
993 // toolkits: undefined,
994 // auth_configs: undefined,
995 // connected_accounts: undefined,
996 // tools: {
997 // overrides: undefined,
998 // filters: {
999 // tags: { include: ['important', 'email'] },
1000 // },
1001 // },
1002 // connections: createExpectedConnections(),
1003 // execution: undefined,
1004 // });
1005 // });
1006
1007 // it('should create a session with disable tag filters', async () => {
1008 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1009
1010 // const config: ToolRouterCreateSessionConfig = {
1011 // tools: {
1012 // tags: { disable: ['dangerous'] },
1013 // },
1014 // };
1015
1016 // await toolRouter.create(userId, config);
1017
1018 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
1019 // user_id: userId,
1020 // toolkits: undefined,
1021 // auth_configs: undefined,
1022 // connected_accounts: undefined,
1023 // tools: {
1024 // overrides: undefined,
1025 // filters: {
1026 // tags: { exclude: ['dangerous'] },
1027 // },
1028 // },
1029 // connections: createExpectedConnections(),
1030 // execution: undefined,
1031 // });
1032 // });
1033
1034 // it('should create a session with both overrides and tag filters', async () => {
1035 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1036
1037 // const config: ToolRouterCreateSessionConfig = {
1038 // tools: {
1039 // overrides: {
1040 // gmail: ['GMAIL_FETCH_EMAILS'],
1041 // slack: { disable: ['SLACK_DELETE_MESSAGE'] },
1042 // },
1043 // tags: ['important'],
1044 // },
1045 // };
1046
1047 // await toolRouter.create(userId, config);
1048
1049 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
1050 // user_id: userId,
1051 // toolkits: undefined,
1052 // auth_configs: undefined,
1053 // connected_accounts: undefined,
1054 // tools: {
1055 // overrides: {
1056 // gmail: { enable: ['GMAIL_FETCH_EMAILS'] },
1057 // slack: { disable: ['SLACK_DELETE_MESSAGE'] },
1058 // },
1059 // filters: {
1060 // tags: { include: ['important'] },
1061 // },
1062 // },
1063 // connections: createExpectedConnections(),
1064 // execution: undefined,
1065 // });
1066 // });
1067 // });
1068
1069 describe('manageConnections configuration', () => {
1070 it('should create a session with manageConnections as boolean (true)', async () => {
1071 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1072
1073 const config: ToolRouterCreateSessionConfig = {
1074 manageConnections: true,
1075 };
1076
1077 await toolRouter.create(userId, config);
1078
1079 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1080 {
1081 user_id: userId,
1082 toolkits: undefined,
1083 auth_configs: undefined,
1084 connected_accounts: undefined,
1085 tools: undefined,
1086 tags: undefined,
1087 manage_connections: createExpectedManageConnections({ enable: true }),
1088 workbench: undefined,
1089 },
1090 undefined
1091 );
1092 });
1093
1094 it('should create a session with manageConnections as boolean (false)', async () => {
1095 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1096
1097 const config: ToolRouterCreateSessionConfig = {
1098 manageConnections: false,
1099 };
1100
1101 await toolRouter.create(userId, config);
1102
1103 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1104 {
1105 user_id: userId,
1106 toolkits: undefined,
1107 auth_configs: undefined,
1108 connected_accounts: undefined,
1109 tools: undefined,
1110 tags: undefined,
1111 manage_connections: createExpectedManageConnections({ enable: false }),
1112 workbench: undefined,
1113 },
1114 undefined
1115 );
1116 });
1117
1118 it('should create a session with manageConnections as object with enable', async () => {
1119 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1120
1121 const config: ToolRouterCreateSessionConfig = {
1122 manageConnections: {
1123 enable: true,
1124 },
1125 };
1126
1127 await toolRouter.create(userId, config);
1128
1129 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1130 {
1131 user_id: userId,
1132 toolkits: undefined,
1133 auth_configs: undefined,
1134 connected_accounts: undefined,
1135 tools: undefined,
1136 tags: undefined,
1137 manage_connections: createExpectedManageConnections({ enable: true }),
1138 workbench: undefined,
1139 },
1140 undefined
1141 );
1142 });
1143
1144 it('should create a session with manageConnections object with callbackUrl', async () => {
1145 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1146
1147 const config: ToolRouterCreateSessionConfig = {
1148 manageConnections: {
1149 enable: true,
1150 callbackUrl: 'https://myapp.com/callback',
1151 },
1152 };
1153
1154 await toolRouter.create(userId, config);
1155
1156 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1157 {
1158 user_id: userId,
1159 toolkits: undefined,
1160 auth_configs: undefined,
1161 connected_accounts: undefined,
1162 tools: undefined,
1163 tags: undefined,
1164 manage_connections: createExpectedManageConnections({
1165 enable: true,
1166 callbackUrl: 'https://myapp.com/callback',
1167 }),
1168 workbench: undefined,
1169 },
1170 undefined
1171 );
1172 });
1173
1174 it('should create a session with full manageConnections configuration', async () => {
1175 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1176
1177 const config: ToolRouterCreateSessionConfig = {
1178 manageConnections: {
1179 enable: true,
1180 callbackUrl: 'https://myapp.com/callback',
1181 },
1182 };
1183
1184 await toolRouter.create(userId, config);
1185
1186 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1187 {
1188 user_id: userId,
1189 toolkits: undefined,
1190 auth_configs: undefined,
1191 connected_accounts: undefined,
1192 tools: undefined,
1193 tags: undefined,
1194 manage_connections: createExpectedManageConnections({
1195 enable: true,
1196 callbackUrl: 'https://myapp.com/callback',
1197 }),
1198 workbench: undefined,
1199 },
1200 undefined
1201 );
1202 });
1203 });
1204
1205 describe('authConfigs and connectedAccounts configuration', () => {
1206 it('should create a session with authConfigs', async () => {
1207 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1208
1209 const config: ToolRouterCreateSessionConfig = {
1210 authConfigs: {
1211 gmail: 'auth_config_123',
1212 slack: 'auth_config_456',
1213 },
1214 };
1215
1216 await toolRouter.create(userId, config);
1217
1218 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1219 {
1220 user_id: userId,
1221 toolkits: undefined,
1222 auth_configs: {
1223 gmail: 'auth_config_123',
1224 slack: 'auth_config_456',
1225 },
1226 connected_accounts: undefined,
1227 tools: undefined,
1228 tags: undefined,
1229 manage_connections: createExpectedManageConnections(),
1230 workbench: undefined,
1231 },
1232 undefined
1233 );
1234 });
1235
1236 it('should create a session with connectedAccounts (string coerced to array)', async () => {
1237 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1238
1239 const config: ToolRouterCreateSessionConfig = {
1240 connectedAccounts: {
1241 gmail: 'conn_123',
1242 slack: ['conn_456'],
1243 },
1244 };
1245
1246 await toolRouter.create(userId, config);
1247
1248 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1249 {
1250 user_id: userId,
1251 toolkits: undefined,
1252 auth_configs: undefined,
1253 connected_accounts: {
1254 gmail: ['conn_123'],
1255 slack: ['conn_456'],
1256 },
1257 tools: undefined,
1258 tags: undefined,
1259 manage_connections: createExpectedManageConnections(),
1260 workbench: undefined,
1261 },
1262 undefined
1263 );
1264 });
1265
1266 it('should create a session with both authConfigs and connectedAccounts', async () => {
1267 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1268
1269 const config: ToolRouterCreateSessionConfig = {
1270 authConfigs: {
1271 gmail: 'auth_config_123',
1272 },
1273 connectedAccounts: {
1274 slack: 'conn_456',
1275 },
1276 };
1277
1278 await toolRouter.create(userId, config);
1279
1280 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1281 {
1282 user_id: userId,
1283 toolkits: undefined,
1284 auth_configs: {
1285 gmail: 'auth_config_123',
1286 },
1287 connected_accounts: {
1288 slack: ['conn_456'],
1289 },
1290 tools: undefined,
1291 tags: undefined,
1292 manage_connections: createExpectedManageConnections(),
1293 workbench: undefined,
1294 },
1295 undefined
1296 );
1297 });
1298 });
1299
1300 describe('workbench configuration', () => {
1301 it('should create a session with enableProxyExecution only', async () => {
1302 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1303
1304 const config: ToolRouterCreateSessionConfig = {
1305 workbench: {
1306 enableProxyExecution: true,
1307 },
1308 };
1309
1310 await toolRouter.create(userId, config);
1311
1312 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1313 {
1314 user_id: userId,
1315 toolkits: undefined,
1316 auth_configs: undefined,
1317 connected_accounts: undefined,
1318 tools: undefined,
1319 tags: undefined,
1320 manage_connections: createExpectedManageConnections(),
1321 workbench: {
1322 enable: true,
1323 enable_proxy_execution: true,
1324 auto_offload_threshold: undefined,
1325 },
1326 },
1327 undefined
1328 );
1329 });
1330
1331 it('should create a session with autoOffloadThreshold only', async () => {
1332 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1333
1334 const config: ToolRouterCreateSessionConfig = {
1335 workbench: {
1336 autoOffloadThreshold: 1000,
1337 },
1338 };
1339
1340 await toolRouter.create(userId, config);
1341
1342 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1343 {
1344 user_id: userId,
1345 toolkits: undefined,
1346 auth_configs: undefined,
1347 connected_accounts: undefined,
1348 tools: undefined,
1349 tags: undefined,
1350 manage_connections: createExpectedManageConnections(),
1351 workbench: {
1352 enable: true,
1353 enable_proxy_execution: undefined,
1354 auto_offload_threshold: 1000,
1355 },
1356 },
1357 undefined
1358 );
1359 });
1360
1361 it('should create a session with full workbench configuration', async () => {
1362 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1363
1364 const config: ToolRouterCreateSessionConfig = {
1365 workbench: {
1366 enableProxyExecution: true,
1367 autoOffloadThreshold: 500,
1368 },
1369 };
1370
1371 await toolRouter.create(userId, config);
1372
1373 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1374 {
1375 user_id: userId,
1376 toolkits: undefined,
1377 auth_configs: undefined,
1378 connected_accounts: undefined,
1379 tools: undefined,
1380 tags: undefined,
1381 manage_connections: createExpectedManageConnections(),
1382 workbench: {
1383 enable: true,
1384 enable_proxy_execution: true,
1385 auto_offload_threshold: 500,
1386 },
1387 },
1388 undefined
1389 );
1390 });
1391
1392 it('should create a session with workbench proxy and offload disabled', async () => {
1393 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1394
1395 const config: ToolRouterCreateSessionConfig = {
1396 workbench: {
1397 enableProxyExecution: false,
1398 autoOffloadThreshold: 0,
1399 },
1400 };
1401
1402 await toolRouter.create(userId, config);
1403
1404 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1405 {
1406 user_id: userId,
1407 toolkits: undefined,
1408 auth_configs: undefined,
1409 connected_accounts: undefined,
1410 tools: undefined,
1411 tags: undefined,
1412 manage_connections: createExpectedManageConnections(),
1413 workbench: {
1414 enable: true,
1415 enable_proxy_execution: false,
1416 auto_offload_threshold: 0,
1417 },
1418 },
1419 undefined
1420 );
1421 });
1422
1423 it('should create a session with workbench entirely disabled', async () => {
1424 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1425
1426 const config: ToolRouterCreateSessionConfig = {
1427 workbench: {
1428 enable: false,
1429 },
1430 };
1431
1432 await toolRouter.create(userId, config);
1433
1434 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1435 {
1436 user_id: userId,
1437 toolkits: undefined,
1438 auth_configs: undefined,
1439 connected_accounts: undefined,
1440 tools: undefined,
1441 tags: undefined,
1442 manage_connections: createExpectedManageConnections(),
1443 workbench: {
1444 enable: false,
1445 enable_proxy_execution: undefined,
1446 auto_offload_threshold: undefined,
1447 },
1448 },
1449 undefined
1450 );
1451 });
1452
1453 it('should create a session with workbench explicitly enabled', async () => {
1454 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1455
1456 const config: ToolRouterCreateSessionConfig = {
1457 workbench: {
1458 enable: true,
1459 enableProxyExecution: true,
1460 autoOffloadThreshold: 20000,
1461 },
1462 };
1463
1464 await toolRouter.create(userId, config);
1465
1466 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1467 {
1468 user_id: userId,
1469 toolkits: undefined,
1470 auth_configs: undefined,
1471 connected_accounts: undefined,
1472 tools: undefined,
1473 tags: undefined,
1474 manage_connections: createExpectedManageConnections(),
1475 workbench: {
1476 enable: true,
1477 enable_proxy_execution: true,
1478 auto_offload_threshold: 20000,
1479 },
1480 },
1481 undefined
1482 );
1483 });
1484
1485 it('forwards sandbox config to the existing workbench wire field', async () => {
1486 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1487
1488 await toolRouter.create(userId, {
1489 sandbox: { enableProxyExecution: false, autoOffloadThreshold: 300, sandboxSize: 'large' },
1490 });
1491
1492 const payload = mockClient.toolRouter.session.create.mock.calls[0]?.[0];
1493 expect(payload?.workbench).toEqual({
1494 enable: true,
1495 enable_proxy_execution: false,
1496 auto_offload_threshold: 300,
1497 sandbox_size: 'large',
1498 });
1499 });
1500
1501 it('forwards sandboxSize as snake_case sandbox_size on the wire', async () => {
1502 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1503
1504 await toolRouter.create(userId, {
1505 workbench: { sandboxSize: 'large' },
1506 });
1507
1508 const payload = mockClient.toolRouter.session.create.mock.calls[0]?.[0];
1509 expect(payload?.workbench?.sandbox_size).toBe('large');
1510 });
1511
1512 it('rejects create config that passes both sandbox and workbench', async () => {
1513 await expect(
1514 toolRouter.create(userId, {
1515 sandbox: { enable: true },
1516 workbench: { enable: true },
1517 })
1518 ).rejects.toThrow('Pass either sandbox or workbench');
1519 });
1520
1521 it('rejects an invalid sandboxSize value via the zod schema', async () => {
1522 await expect(
1523 toolRouter.create(userId, {
1524 workbench: { sandboxSize: 'huge' },
1525 } as unknown as ToolRouterCreateSessionConfig)
1526 ).rejects.toThrow();
1527 });
1528 });
1529
1530 // describe('complex configuration combinations', () => {
1531 // it('should create a session with all configuration options', async () => {
1532 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1533
1534 // const config: ToolRouterCreateSessionConfig = {
1535 // toolkits: ['gmail', 'slack'],
1536 // tools: {
1537 // overrides: {
1538 // gmail: ['GMAIL_FETCH_EMAILS'],
1539 // },
1540 // tags: ['important'],
1541 // },
1542 // authConfigs: {
1543 // gmail: 'auth_config_123',
1544 // },
1545 // connectedAccounts: {
1546 // slack: 'conn_456',
1547 // },
1548 // manageConnections: {
1549 // enable: true,
1550 // callbackUri: 'https://myapp.com/callback',
1551 // },
1552 // execution: {
1553 // enableProxyExecution: true,
1554 // autoOffloadThreshould: 30,
1555 // },
1556 // };
1557
1558 // await toolRouter.create(userId, config);
1559
1560 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
1561 // user_id: userId,
1562 // toolkits: {
1563 // enable: ['gmail', 'slack'],
1564 // },
1565 // auth_configs: {
1566 // gmail: 'auth_config_123',
1567 // },
1568 // connected_accounts: {
1569 // slack: 'conn_456',
1570 // },
1571 // tools: {
1572 // overrides: {
1573 // gmail: { enable: ['GMAIL_FETCH_EMAILS'] },
1574 // },
1575 // filters: {
1576 // tags: { include: ['important'] },
1577 // },
1578 // },
1579 // connections: createExpectedConnections({
1580 // manageConnections: true,
1581 // callbackUri: 'https://myapp.com/callback',
1582 // }),
1583 // execution: {
1584 // enable_proxy_execution: true,
1585 // auto_offload_threshould: 30,
1586 // },
1587 // });
1588 // });
1589
1590 // it('should create a session with toolkits and disable tools', async () => {
1591 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1592
1593 // const config: ToolRouterCreateSessionConfig = {
1594 // toolkits: {
1595 // enable: ['gmail', 'slack', 'github'],
1596 // },
1597 // tools: {
1598 // overrides: {
1599 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
1600 // slack: { disable: ['SLACK_DELETE_MESSAGE'] },
1601 // },
1602 // },
1603 // };
1604
1605 // await toolRouter.create(userId, config);
1606
1607 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
1608 // user_id: userId,
1609 // toolkits: {
1610 // enable: ['gmail', 'slack', 'github'],
1611 // },
1612 // auth_configs: undefined,
1613 // connected_accounts: undefined,
1614 // tools: {
1615 // overrides: {
1616 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
1617 // slack: { disable: ['SLACK_DELETE_MESSAGE'] },
1618 // },
1619 // filters: undefined,
1620 // },
1621 // connections: createExpectedConnections(),
1622 // execution: undefined,
1623 // });
1624 // });
1625
1626 // it('should create a session with complex nested configuration', async () => {
1627 // mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1628
1629 // const config: ToolRouterCreateSessionConfig = {
1630 // toolkits: {
1631 // disable: ['notion'],
1632 // },
1633 // tools: {
1634 // overrides: {
1635 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
1636 // },
1637 // tags: { disable: ['dangerous'] },
1638 // },
1639 // authConfigs: {
1640 // gmail: 'auth_config_123',
1641 // slack: 'auth_config_456',
1642 // github: 'auth_config_789',
1643 // },
1644 // connectedAccounts: {},
1645 // manageConnections: {
1646 // enable: false,
1647 // },
1648 // };
1649
1650 // await toolRouter.create(userId, config);
1651
1652 // expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith({
1653 // user_id: userId,
1654 // toolkits: {
1655 // disable: ['notion'],
1656 // },
1657 // auth_configs: {
1658 // gmail: 'auth_config_123',
1659 // slack: 'auth_config_456',
1660 // github: 'auth_config_789',
1661 // },
1662 // connected_accounts: {},
1663 // tools: {
1664 // overrides: {
1665 // gmail: { disable: ['GMAIL_DELETE_EMAIL'] },
1666 // },
1667 // filters: {
1668 // tags: { exclude: ['dangerous'] },
1669 // },
1670 // },
1671 // connections: createExpectedConnections({
1672 // manageConnections: false,
1673 // }),
1674 // execution: undefined,
1675 // });
1676 // });
1677 // });
1678
1679 describe('multiAccount configuration', () => {
1680 it('should create a session with multiAccount enable only', async () => {
1681 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1682
1683 const config: ToolRouterCreateSessionConfig = {
1684 multiAccount: {
1685 enable: true,
1686 },
1687 };
1688
1689 await toolRouter.create(userId, config);
1690
1691 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1692 expect.objectContaining({
1693 user_id: userId,
1694 multi_account: {
1695 enable: true,
1696 max_accounts_per_toolkit: undefined,
1697 require_explicit_selection: true,
1698 },
1699 }),
1700 undefined
1701 );
1702 });
1703
1704 it('should create a session with full multiAccount configuration', async () => {
1705 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1706
1707 const config: ToolRouterCreateSessionConfig = {
1708 multiAccount: {
1709 enable: true,
1710 maxAccountsPerToolkit: 3,
1711 requireExplicitSelection: true,
1712 },
1713 };
1714
1715 await toolRouter.create(userId, config);
1716
1717 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1718 expect.objectContaining({
1719 user_id: userId,
1720 multi_account: {
1721 enable: true,
1722 max_accounts_per_toolkit: 3,
1723 require_explicit_selection: true,
1724 },
1725 }),
1726 undefined
1727 );
1728 });
1729
1730 it('should not include multi_account when multiAccount is not provided', async () => {
1731 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1732
1733 await toolRouter.create(userId, {});
1734
1735 const callArgs = mockClient.toolRouter.session.create.mock.calls[0][0];
1736 expect(callArgs.multi_account).toBeUndefined();
1737 });
1738
1739 it('should create a session with multiAccount combined with other options', async () => {
1740 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1741
1742 const config: ToolRouterCreateSessionConfig = {
1743 toolkits: ['gmail', 'slack'],
1744 multiAccount: {
1745 enable: true,
1746 maxAccountsPerToolkit: 5,
1747 },
1748 };
1749
1750 await toolRouter.create(userId, config);
1751
1752 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1753 expect.objectContaining({
1754 user_id: userId,
1755 toolkits: { enable: ['gmail', 'slack'] },
1756 multi_account: {
1757 enable: true,
1758 max_accounts_per_toolkit: 5,
1759 require_explicit_selection: true,
1760 },
1761 }),
1762 undefined
1763 );
1764 });
1765 });
1766
1767 describe('experimental configuration', () => {
1768 it('should create a session with experimental assistivePrompt userTimezone', async () => {
1769 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1770
1771 const config: ToolRouterCreateSessionConfig = {
1772 experimental: {
1773 assistivePrompt: {
1774 userTimezone: 'America/New_York',
1775 },
1776 },
1777 };
1778
1779 await toolRouter.create(userId, config);
1780
1781 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1782 {
1783 user_id: userId,
1784 toolkits: undefined,
1785 auth_configs: undefined,
1786 connected_accounts: undefined,
1787 tools: undefined,
1788 tags: undefined,
1789 manage_connections: createExpectedManageConnections(),
1790 workbench: undefined,
1791 experimental: {
1792 assistive_prompt_config: {
1793 user_timezone: 'America/New_York',
1794 },
1795 },
1796 },
1797 undefined
1798 );
1799 });
1800
1801 it('should not include experimental in payload when assistivePrompt is not provided', async () => {
1802 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1803
1804 const config: ToolRouterCreateSessionConfig = {
1805 experimental: {},
1806 };
1807
1808 await toolRouter.create(userId, config);
1809
1810 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1811 {
1812 user_id: userId,
1813 toolkits: undefined,
1814 auth_configs: undefined,
1815 connected_accounts: undefined,
1816 tools: undefined,
1817 tags: undefined,
1818 manage_connections: createExpectedManageConnections(),
1819 workbench: undefined,
1820 experimental: undefined,
1821 },
1822 undefined
1823 );
1824 });
1825
1826 it('should not include experimental in payload when userTimezone is not provided', async () => {
1827 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1828
1829 const config: ToolRouterCreateSessionConfig = {
1830 experimental: {
1831 assistivePrompt: {},
1832 },
1833 };
1834
1835 await toolRouter.create(userId, config);
1836
1837 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1838 {
1839 user_id: userId,
1840 toolkits: undefined,
1841 auth_configs: undefined,
1842 connected_accounts: undefined,
1843 tools: undefined,
1844 tags: undefined,
1845 manage_connections: createExpectedManageConnections(),
1846 workbench: undefined,
1847 experimental: undefined,
1848 },
1849 undefined
1850 );
1851 });
1852
1853 it('should create a session with experimental config combined with other options', async () => {
1854 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1855
1856 const config: ToolRouterCreateSessionConfig = {
1857 toolkits: ['gmail', 'slack'],
1858 experimental: {
1859 assistivePrompt: {
1860 userTimezone: 'Europe/London',
1861 },
1862 },
1863 };
1864
1865 await toolRouter.create(userId, config);
1866
1867 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
1868 {
1869 user_id: userId,
1870 toolkits: {
1871 enable: ['gmail', 'slack'],
1872 },
1873 auth_configs: undefined,
1874 connected_accounts: undefined,
1875 tools: undefined,
1876 tags: undefined,
1877 manage_connections: createExpectedManageConnections(),
1878 workbench: undefined,
1879 experimental: {
1880 assistive_prompt_config: {
1881 user_timezone: 'Europe/London',
1882 },
1883 },
1884 },
1885 undefined
1886 );
1887 });
1888
1889 it('should transform experimental assistive_prompt from API response to SDK format', async () => {
1890 const responseWithExperimental = {
1891 ...mockSessionCreateResponse,
1892 experimental: {
1893 assistive_prompt:
1894 'You are a helpful assistant working in the America/New_York timezone.',
1895 },
1896 };
1897
1898 mockClient.toolRouter.session.create.mockResolvedValueOnce(responseWithExperimental);
1899
1900 const session = await toolRouter.create(userId, {
1901 experimental: {
1902 assistivePrompt: {
1903 userTimezone: 'America/New_York',
1904 },
1905 },
1906 });
1907
1908 expect(session.experimental.assistivePrompt).toEqual(
1909 'You are a helpful assistant working in the America/New_York timezone.'
1910 );
1911 expect(session.experimental.files).toBeDefined();
1912 });
1913
1914 it('should handle API response without experimental field', async () => {
1915 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1916
1917 const session = await toolRouter.create(userId);
1918
1919 expect(session.experimental).toBeDefined();
1920 expect(session.experimental.assistivePrompt).toBeUndefined();
1921 expect(session.experimental.files).toBeDefined();
1922 });
1923 });
1924
1925 describe('approval rules', () => {
1926 const createPayload = () => mockClient.toolRouter.session.create.mock.calls[0][0];
1927
1928 it('sends requireApproval lists as require_approval', async () => {
1929 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1930
1931 await toolRouter.create(userId, {
1932 toolkits: { enable: ['gmail', 'github'], requireApproval: ['github'] },
1933 tools: {
1934 gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] },
1935 slack: { tags: { requireApproval: ['destructiveHint'] } },
1936 },
1937 tags: { requireApproval: ['destructiveHint'] },
1938 });
1939
1940 expect(createPayload()).toMatchObject({
1941 toolkits: { enable: ['gmail', 'github'], require_approval: ['github'] },
1942 tools: {
1943 gmail: { require_approval: ['GMAIL_SEND_EMAIL'] },
1944 slack: { tags: { require_approval: ['destructiveHint'] } },
1945 },
1946 tags: { require_approval: ['destructiveHint'] },
1947 });
1948 });
1949
1950 it('sends noElicitationSupportFallback as experimental.no_elicitation_support_fallback', async () => {
1951 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1952
1953 await toolRouter.create(userId, {
1954 toolkits: { requireApproval: ['gmail'] },
1955 experimental: { noElicitationSupportFallback: 'allow' },
1956 });
1957
1958 expect(createPayload().toolkits).toEqual({ require_approval: ['gmail'] });
1959 expect(createPayload().experimental).toEqual({ no_elicitation_support_fallback: 'allow' });
1960 });
1961 });
1962
1963 describe('session configs', () => {
1964 const createPayload = () => mockClient.toolRouter.session.create.mock.calls[0][0];
1965
1966 it('sends sessionConfigId as experimental.session_config_id', async () => {
1967 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1968
1969 await toolRouter.create(userId, { experimental: { sessionConfigId: 'sc_1' } });
1970
1971 expect(createPayload().experimental).toEqual({ session_config_id: 'sc_1' });
1972 });
1973
1974 it('sends the same payload as before when no sessionConfigId is set', async () => {
1975 mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
1976
1977 await toolRouter.create(userId);
1978 await toolRouter.create(userId, { toolkits: ['gmail'] });
1979
1980 const [[bare], [withToolkits]] = mockClient.toolRouter.session.create.mock.calls;
1981 expect(bare.experimental).toBeUndefined();
1982 expect(withToolkits.experimental).toBeUndefined();
1983 expect(JSON.stringify(bare)).toBe(
1984 JSON.stringify({ user_id: userId, manage_connections: { enable: true } })
1985 );
1986 expect(JSON.stringify(withToolkits)).toBe(
1987 JSON.stringify({
1988 user_id: userId,
1989 toolkits: { enable: ['gmail'] },
1990 manage_connections: { enable: true },
1991 })
1992 );
1993 });
1994
1995 it('sends session_config_id together with assistive_prompt_config', async () => {
1996 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
1997
1998 await toolRouter.create(userId, {
1999 experimental: {
2000 sessionConfigId: 'sc_1',
2001 assistivePrompt: { userTimezone: 'Europe/Rome' },
2002 },
2003 });
2004
2005 expect(createPayload().experimental).toEqual({
2006 session_config_id: 'sc_1',
2007 assistive_prompt_config: { user_timezone: 'Europe/Rome' },
2008 });
2009 });
2010
2011 it('sends every per-session field unchanged next to sessionConfigId', async () => {
2012 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2013
2014 await toolRouter.create(userId, {
2015 authConfigs: { github: 'ac_1' },
2016 connectedAccounts: { github: 'ca_1' },
2017 manageConnections: false,
2018 sandbox: { enable: false },
2019 multiAccount: { enable: true, maxAccountsPerToolkit: 3 },
2020 preload: { tools: ['GITHUB_GET_REPO'] },
2021 experimental: { sessionConfigId: 'sc_1' },
2022 });
2023
2024 expect(createPayload()).toEqual({
2025 user_id: userId,
2026 auth_configs: { github: 'ac_1' },
2027 connected_accounts: { github: ['ca_1'] },
2028 manage_connections: { enable: false },
2029 workbench: { enable: false },
2030 multi_account: {
2031 enable: true,
2032 max_accounts_per_toolkit: 3,
2033 require_explicit_selection: true,
2034 },
2035 preload: { tools: ['GITHUB_GET_REPO'] },
2036 experimental: { session_config_id: 'sc_1' },
2037 });
2038 });
2039
2040 it('rejects an empty sessionConfigId before any client call', async () => {
2041 await expect(
2042 toolRouter.create(userId, { experimental: { sessionConfigId: '' } })
2043 ).rejects.toThrow();
2044 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
2045 });
2046
2047 // Plain JavaScript callers bypass the compile-time union, so these go
2048 // through `unknown`.
2049 const createUnchecked = (config: Record<string, unknown>) =>
2050 toolRouter.create(userId, config as unknown as ToolRouterCreateSessionConfig);
2051 const customTool = { slug: 'MY_TOOL' };
2052 const customToolkit = { slug: 'MY_TOOLKIT', tools: [] };
2053
2054 it.each([
2055 ['toolkits', { toolkits: ['github'] }],
2056 ['toolkits', { toolkits: { disable: ['x'] } }],
2057 ['tools', { tools: { github: ['GITHUB_GET_REPO'] } }],
2058 ['tags', { tags: ['readOnlyHint'] }],
2059 ['experimental.localTools', { experimental: { localTools: [customTool] } }],
2060 ['experimental.localToolkits', { experimental: { localToolkits: [customToolkit] } }],
2061 ['experimental.customTools', { experimental: { customTools: [customTool] } }],
2062 ['experimental.customToolkits', { experimental: { customToolkits: [customToolkit] } }],
2063 ['toolkits', { toolkits: [] }],
2064 ['experimental.localTools', { experimental: { localTools: [] } }],
2065 ['experimental.customTools', { experimental: { customTools: [] } }],
2066 ])(
2067 'rejects sessionConfigId combined with %s (%j) without calling the API',
2068 async (field, inline) => {
2069 const inlineExperimental = (inline as { experimental?: object }).experimental;
2070 const error = await createUnchecked({
2071 ...inline,
2072 experimental: { ...inlineExperimental, sessionConfigId: 'sc_1' },
2073 }).catch(e => e);
2074
2075 expect(error).toBeInstanceOf(ValidationError);
2076 expect(error.message).toContain(
2077 `experimental.sessionConfigId cannot be combined with ${field}`
2078 );
2079 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
2080 }
2081 );
2082
2083 it('names every conflicting field in one error', async () => {
2084 const error = await createUnchecked({
2085 toolkits: ['github'],
2086 tags: ['readOnlyHint'],
2087 experimental: { sessionConfigId: 'sc_1', customTools: [customTool] },
2088 }).catch(e => e);
2089
2090 expect(error).toBeInstanceOf(ValidationError);
2091 expect(error.message).toContain(
2092 'experimental.sessionConfigId cannot be combined with toolkits, tags, experimental.customTools'
2093 );
2094 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
2095 });
2096
2097 it('treats an explicit undefined inline field as absent', async () => {
2098 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2099
2100 await toolRouter.create(userId, {
2101 toolkits: undefined,
2102 experimental: { sessionConfigId: 'sc_1' },
2103 });
2104
2105 expect(createPayload().experimental).toEqual({ session_config_id: 'sc_1' });
2106 });
2107
2108 it('keeps throwing ZodError for unrelated invalid input', async () => {
2109 const error = await createUnchecked({
2110 multiAccount: { maxAccountsPerToolkit: 1 },
2111 }).catch(e => e);
2112
2113 expect(error).toBeInstanceOf(z.ZodError);
2114 expect(error).not.toBeInstanceOf(ValidationError);
2115 expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
2116 });
2117
2118 it('allows the direct tools preset with a saved config and sends preload all', async () => {
2119 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2120
2121 await toolRouter.create(userId, {
2122 sessionPreset: SessionPreset.DIRECT_TOOLS,
2123 experimental: { sessionConfigId: 'sc_1' },
2124 });
2125
2126 expect(createPayload()).toMatchObject({
2127 preload: { tools: 'all' },
2128 experimental: { session_config_id: 'sc_1' },
2129 });
2130 });
2131 });
2132
2133 describe('error handling', () => {
2134 it('should throw error if API call fails', async () => {
2135 const apiError = new Error('API error: Invalid session configuration');
2136 mockClient.toolRouter.session.create.mockRejectedValueOnce(apiError);
2137
2138 await expect(toolRouter.create(userId)).rejects.toThrow(
2139 'API error: Invalid session configuration'
2140 );
2141
2142 expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
2143 });
2144
2145 it('should throw error for invalid configuration', async () => {
2146 const invalidConfig = {
2147 toolkits: 'invalid-toolkits', // Should be array or object
2148 } as unknown;
2149
2150 await expect(toolRouter.create(userId, invalidConfig)).rejects.toThrow();
2151 });
2152
2153 it('should pass through empty userId', async () => {
2154 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2155
2156 // The test validates that even empty userId is passed through
2157 // The API layer would handle the validation
2158 await toolRouter.create('');
2159
2160 expect(mockClient.toolRouter.session.create).toHaveBeenCalledWith(
2161 expect.objectContaining({
2162 user_id: '',
2163 }),
2164 undefined
2165 );
2166 });
2167 });
2168
2169 describe('response handling', () => {
2170 it('should handle MCP type correctly', async () => {
2171 const responseWithHttp = {
2172 ...mockSessionCreateResponse,
2173 mcp: {
2174 type: 'http',
2175 url: 'https://api.composio.dev/api/v3/tool_router/session/session_123',
2176 },
2177 };
2178
2179 mockClient.toolRouter.session.create.mockResolvedValueOnce(responseWithHttp);
2180
2181 const session = await toolRouter.create(userId);
2182
2183 expect(session.mcp.type).toBe('http');
2184 });
2185
2186 it('should handle SSE MCP type correctly', async () => {
2187 const sseResponse = {
2188 ...mockSessionCreateResponse,
2189 mcp: {
2190 type: 'sse',
2191 url: 'https://api.composio.dev/api/v3/tool_router/session/sse/session_123',
2192 },
2193 };
2194
2195 mockClient.toolRouter.session.create.mockResolvedValueOnce(sseResponse);
2196
2197 const session = await toolRouter.create(userId);
2198
2199 expect(session.mcp.type).toBe('sse');
2200 expect(session.mcp.url).toBe(
2201 'https://api.composio.dev/api/v3/tool_router/session/sse/session_123'
2202 );
2203 });
2204
2205 it('should return session with all required properties', async () => {
2206 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2207
2208 const session = await toolRouter.create(userId);
2209
2210 expect(session).toHaveProperty('sessionId');
2211 expect(session).toHaveProperty('mcp');
2212 expect(session).toHaveProperty('tools');
2213 expect(session).toHaveProperty('authorize');
2214 expect(session).toHaveProperty('toolkits');
2215
2216 expect(typeof session.tools).toBe('function');
2217 expect(typeof session.authorize).toBe('function');
2218 expect(typeof session.toolkits).toBe('function');
2219 });
2220 });
2221 });
2222
2223 describe('authorize function', () => {
2224 const userId = 'user_123';
2225 const sessionId = 'session_123';
2226 const toolkit = 'gmail';
2227
2228 beforeEach(async () => {
2229 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2230 });
2231
2232 it('should authorize a toolkit without callbackUrl', async () => {
2233 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
2234
2235 const session = await toolRouter.create(userId);
2236 const connectionRequest = await session.authorize(toolkit);
2237
2238 expect(mockClient.toolRouter.session.link).toHaveBeenCalledWith(
2239 sessionId,
2240 {
2241 toolkit,
2242 },
2243 undefined
2244 );
2245
2246 expect(connectionRequest).toHaveProperty('id', 'conn_456');
2247 expect(connectionRequest).toHaveProperty('status', ConnectedAccountStatuses.INITIATED);
2248 expect(connectionRequest).toHaveProperty('redirectUrl', 'https://composio.dev/auth/redirect');
2249 });
2250
2251 it('should authorize a toolkit with callbackUrl', async () => {
2252 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
2253
2254 const session = await toolRouter.create(userId);
2255 const connectionRequest = await session.authorize(toolkit, {
2256 callbackUrl: 'https://myapp.com/callback',
2257 });
2258
2259 expect(mockClient.toolRouter.session.link).toHaveBeenCalledWith(
2260 sessionId,
2261 {
2262 toolkit,
2263 callback_url: 'https://myapp.com/callback',
2264 },
2265 undefined
2266 );
2267
2268 expect(connectionRequest.id).toBe('conn_456');
2269 expect(connectionRequest.redirectUrl).toBe('https://composio.dev/auth/redirect');
2270 });
2271
2272 it('should authorize multiple toolkits in sequence', async () => {
2273 const slackLinkResponse = {
2274 connected_account_id: 'conn_789',
2275 redirect_url: 'https://composio.dev/auth/slack/redirect',
2276 };
2277
2278 mockClient.toolRouter.session.link
2279 .mockResolvedValueOnce(mockLinkResponse)
2280 .mockResolvedValueOnce(slackLinkResponse);
2281
2282 const session = await toolRouter.create(userId);
2283
2284 const gmailConnection = await session.authorize('gmail');
2285 const slackConnection = await session.authorize('slack');
2286
2287 expect(mockClient.toolRouter.session.link).toHaveBeenCalledTimes(2);
2288 expect(gmailConnection.id).toBe('conn_456');
2289 expect(slackConnection.id).toBe('conn_789');
2290 });
2291
2292 it('should handle authorization errors', async () => {
2293 const authError = new Error('Authorization failed: Invalid toolkit');
2294 mockClient.toolRouter.session.link.mockRejectedValueOnce(authError);
2295
2296 const session = await toolRouter.create(userId);
2297
2298 await expect(session.authorize(toolkit)).rejects.toThrow(
2299 'Authorization failed: Invalid toolkit'
2300 );
2301
2302 expect(mockClient.toolRouter.session.link).toHaveBeenCalledWith(
2303 sessionId,
2304 {
2305 toolkit,
2306 },
2307 undefined
2308 );
2309 });
2310
2311 it('should handle network errors during authorization', async () => {
2312 const networkError = new Error('Network error');
2313 mockClient.toolRouter.session.link.mockRejectedValueOnce(networkError);
2314
2315 const session = await toolRouter.create(userId);
2316
2317 await expect(session.authorize(toolkit)).rejects.toThrow('Network error');
2318 });
2319
2320 it('should create ConnectionRequest with correct parameters', async () => {
2321 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
2322
2323 const session = await toolRouter.create(userId);
2324 const connectionRequest = await session.authorize(toolkit);
2325
2326 // Verify the connection request has the expected methods
2327 expect(connectionRequest).toHaveProperty('waitForConnection');
2328 expect(connectionRequest).toHaveProperty('toJSON');
2329 expect(connectionRequest).toHaveProperty('toString');
2330 expect(typeof connectionRequest.waitForConnection).toBe('function');
2331 });
2332
2333 // authorize() validates experimental.aclConfigForShared at the SDK
2334 // boundary — same caps as link() (1000-entry list, 256-char user_id).
2335 it('forwards the experimental block to the wire', async () => {
2336 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
2337
2338 const session = await toolRouter.create(userId);
2339 await session.authorize(toolkit, {
2340 experimental: {
2341 accountType: 'SHARED',
2342 aclConfigForShared: {
2343 allowAllUsers: true,
2344 notAllowedUserIds: ['user_bob'],
2345 },
2346 },
2347 });
2348
2349 expect(mockClient.toolRouter.session.link).toHaveBeenCalledWith(
2350 sessionId,
2351 {
2352 toolkit,
2353 experimental: {
2354 account_type: 'SHARED',
2355 acl_config_for_shared: {
2356 allow_all_users: true,
2357 not_allowed_user_ids: ['user_bob'],
2358 },
2359 },
2360 },
2361 undefined
2362 );
2363 });
2364
2365 it('omits the experimental block entirely when not provided', async () => {
2366 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
2367
2368 const session = await toolRouter.create(userId);
2369 await session.authorize(toolkit);
2370
2371 const body = mockClient.toolRouter.session.link.mock.calls[0][1];
2372 expect('experimental' in body).toBe(false);
2373 });
2374
2375 it('throws ValidationError when allowedUserIds exceeds the 1000-entry cap', async () => {
2376 const session = await toolRouter.create(userId);
2377 const oversizedList = Array.from({ length: 1001 }, (_, i) => `user_${i}`);
2378
2379 await expect(
2380 session.authorize(toolkit, {
2381 experimental: {
2382 accountType: 'SHARED',
2383 aclConfigForShared: { allowedUserIds: oversizedList },
2384 },
2385 })
2386 ).rejects.toMatchObject({ name: 'ValidationError' });
2387
2388 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2389 });
2390
2391 it('throws ValidationError when a user_id exceeds the 256-char length cap', async () => {
2392 const session = await toolRouter.create(userId);
2393 const tooLongUserId = 'u'.repeat(257);
2394
2395 await expect(
2396 session.authorize(toolkit, {
2397 experimental: {
2398 accountType: 'SHARED',
2399 aclConfigForShared: { allowedUserIds: [tooLongUserId] },
2400 },
2401 })
2402 ).rejects.toMatchObject({ name: 'ValidationError' });
2403
2404 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2405 });
2406
2407 it('throws ValidationError when a user_id is empty', async () => {
2408 const session = await toolRouter.create(userId);
2409
2410 await expect(
2411 session.authorize(toolkit, {
2412 experimental: {
2413 accountType: 'SHARED',
2414 aclConfigForShared: { notAllowedUserIds: [''] },
2415 },
2416 })
2417 ).rejects.toMatchObject({ name: 'ValidationError' });
2418
2419 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2420 });
2421 });
2422
2423 describe('ensureConnected function', () => {
2424 const userId = 'user_123';
2425 const sessionId = 'session_123';
2426
2427 beforeEach(async () => {
2428 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2429 });
2430
2431 it('returns the active connection without linking when the toolkit is already connected', async () => {
2432 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2433
2434 const session = await toolRouter.create(userId);
2435 const result = await session.ensureConnected('gmail');
2436
2437 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2438 sessionId,
2439 expect.objectContaining({ toolkits: ['gmail'] }),
2440 undefined
2441 );
2442 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2443 expect(result).toEqual({
2444 toolkit: 'gmail',
2445 wasConnected: true,
2446 connectedAccount: { id: 'conn_123', status: 'ACTIVE' },
2447 });
2448 });
2449
2450 it('treats a no-auth toolkit as connected without linking', async () => {
2451 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce({
2452 items: [{ slug: 'search', name: 'Search', is_no_auth: true, connected_account: null }],
2453 next_cursor: null,
2454 total_pages: 1,
2455 });
2456
2457 const session = await toolRouter.create(userId);
2458 const result = await session.ensureConnected('search');
2459
2460 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2461 expect(result).toEqual({ toolkit: 'search', wasConnected: true });
2462 });
2463
2464 it('links and waits for a connection when the toolkit has none', async () => {
2465 // github has connected_account: null in the shared mock response.
2466 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2467
2468 const session = await toolRouter.create(userId);
2469 const waitForConnection = vi.fn().mockResolvedValue({ id: 'conn_456', status: 'ACTIVE' });
2470 const authorizeSpy = vi.spyOn(session, 'authorize').mockResolvedValue({
2471 id: 'conn_456',
2472 status: ConnectedAccountStatuses.INITIATED,
2473 redirectUrl: 'https://composio.dev/auth/redirect',
2474 waitForConnection,
2475 } as unknown as ConnectionRequest);
2476
2477 const result = await session.ensureConnected('github', { timeout: 5000 });
2478
2479 expect(authorizeSpy).toHaveBeenCalledWith('github', {}, undefined);
2480 expect(waitForConnection).toHaveBeenCalledWith(5000);
2481 expect(result).toEqual({
2482 toolkit: 'github',
2483 wasConnected: false,
2484 connectedAccount: { id: 'conn_456', status: 'ACTIVE' },
2485 });
2486 });
2487
2488 it('links a new connection when the only linked account is still pending', async () => {
2489 // slack has an INITIATED (non-active) connected_account in the shared mock.
2490 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2491
2492 const session = await toolRouter.create(userId);
2493 const waitForConnection = vi.fn().mockResolvedValue({ id: 'conn_789', status: 'ACTIVE' });
2494 const authorizeSpy = vi.spyOn(session, 'authorize').mockResolvedValue({
2495 id: 'conn_789',
2496 status: ConnectedAccountStatuses.INITIATED,
2497 redirectUrl: null,
2498 waitForConnection,
2499 } as unknown as ConnectionRequest);
2500
2501 const result = await session.ensureConnected('slack');
2502
2503 expect(authorizeSpy).toHaveBeenCalledWith('slack', {}, undefined);
2504 expect(waitForConnection).toHaveBeenCalledWith(undefined);
2505 expect(result).toEqual({
2506 toolkit: 'slack',
2507 wasConnected: false,
2508 connectedAccount: { id: 'conn_789', status: 'ACTIVE' },
2509 });
2510 });
2511
2512 it('rejects invalid timeout options without calling the API', async () => {
2513 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2514 const session = await toolRouter.create(userId);
2515
2516 await expect(session.ensureConnected('github', { timeout: -1 })).rejects.toMatchObject({
2517 name: 'ValidationError',
2518 });
2519 expect(mockClient.toolRouter.session.toolkits).not.toHaveBeenCalled();
2520 expect(mockClient.toolRouter.session.link).not.toHaveBeenCalled();
2521 });
2522 });
2523
2524 describe('toolkits function', () => {
2525 const userId = 'user_123';
2526 const sessionId = 'session_123';
2527
2528 beforeEach(async () => {
2529 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2530 });
2531
2532 it('should fetch toolkits without options', async () => {
2533 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2534
2535 const session = await toolRouter.create(userId);
2536 const result = await session.toolkits();
2537
2538 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2539 sessionId,
2540 {
2541 cursor: undefined,
2542 limit: undefined,
2543 toolkits: undefined,
2544 is_connected: undefined,
2545 },
2546 undefined
2547 );
2548
2549 expect(result).toHaveProperty('items');
2550 expect(result).toHaveProperty('cursor', 'cursor_789');
2551 expect(result).toHaveProperty('totalPages', 2);
2552 expect(result.items).toHaveLength(3);
2553 });
2554
2555 it('should fetch toolkits with pagination options', async () => {
2556 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2557
2558 const session = await toolRouter.create(userId);
2559 const result = await session.toolkits({
2560 limit: 10,
2561 cursor: 'cursor_abc',
2562 });
2563
2564 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2565 sessionId,
2566 {
2567 cursor: 'cursor_abc',
2568 limit: 10,
2569 toolkits: undefined,
2570 is_connected: undefined,
2571 },
2572 undefined
2573 );
2574
2575 expect(result.items).toHaveLength(3);
2576 });
2577
2578 it('should fetch toolkits with toolkits filter option', async () => {
2579 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2580
2581 const session = await toolRouter.create(userId);
2582 const result = await session.toolkits({
2583 toolkits: ['gmail', 'slack'],
2584 });
2585
2586 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2587 sessionId,
2588 {
2589 cursor: undefined,
2590 limit: undefined,
2591 toolkits: ['gmail', 'slack'],
2592 is_connected: undefined,
2593 },
2594 undefined
2595 );
2596
2597 expect(result.items).toHaveLength(3);
2598 });
2599
2600 it('should fetch toolkits with isConnected filter option', async () => {
2601 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2602
2603 const session = await toolRouter.create(userId);
2604 const result = await session.toolkits({
2605 isConnected: true,
2606 });
2607
2608 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2609 sessionId,
2610 {
2611 cursor: undefined,
2612 limit: undefined,
2613 toolkits: undefined,
2614 is_connected: true,
2615 },
2616 undefined
2617 );
2618
2619 expect(result.items).toHaveLength(3);
2620 });
2621
2622 it('should fetch toolkits with both pagination and toolkits filter options', async () => {
2623 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2624
2625 const session = await toolRouter.create(userId);
2626 const result = await session.toolkits({
2627 limit: 5,
2628 cursor: 'cursor_xyz',
2629 toolkits: ['github'],
2630 });
2631
2632 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2633 sessionId,
2634 {
2635 cursor: 'cursor_xyz',
2636 limit: 5,
2637 toolkits: ['github'],
2638 is_connected: undefined,
2639 },
2640 undefined
2641 );
2642
2643 expect(result.items).toHaveLength(3);
2644 });
2645
2646 it('should fetch toolkits with all options combined', async () => {
2647 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2648
2649 const session = await toolRouter.create(userId);
2650 const result = await session.toolkits({
2651 limit: 5,
2652 cursor: 'cursor_xyz',
2653 toolkits: ['github', 'gmail'],
2654 isConnected: false,
2655 });
2656
2657 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
2658 sessionId,
2659 {
2660 cursor: 'cursor_xyz',
2661 limit: 5,
2662 toolkits: ['github', 'gmail'],
2663 is_connected: false,
2664 },
2665 undefined
2666 );
2667
2668 expect(result.items).toHaveLength(3);
2669 });
2670
2671 it('should transform toolkit connection state correctly for active connection', async () => {
2672 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2673
2674 const session = await toolRouter.create(userId);
2675 const result = await session.toolkits();
2676
2677 const gmailToolkit = result.items[0];
2678 expect(gmailToolkit.slug).toBe('gmail');
2679 expect(gmailToolkit.name).toBe('Gmail');
2680 expect(gmailToolkit.logo).toBe('https://example.com/gmail-logo.png');
2681 expect(gmailToolkit.isNoAuth).toBe(false);
2682 expect(gmailToolkit.connection?.isActive).toBe(true);
2683 expect(gmailToolkit.connection?.authConfig).toEqual({
2684 id: 'auth_config_123',
2685 mode: 'OAUTH2',
2686 isComposioManaged: true,
2687 });
2688 expect(gmailToolkit.connection?.connectedAccount).toEqual({
2689 id: 'conn_123',
2690 status: 'ACTIVE',
2691 });
2692 });
2693
2694 it('should transform toolkit connection state correctly for initiated connection', async () => {
2695 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2696
2697 const session = await toolRouter.create(userId);
2698 const result = await session.toolkits();
2699
2700 const slackToolkit = result.items[1];
2701 expect(slackToolkit.slug).toBe('slack');
2702 expect(slackToolkit.connection?.isActive).toBe(false);
2703 expect(slackToolkit.connection?.connectedAccount?.status).toBe('INITIATED');
2704 });
2705
2706 it('should transform toolkit connection state correctly for no connection', async () => {
2707 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
2708
2709 const session = await toolRouter.create(userId);
2710 const result = await session.toolkits();
2711
2712 const githubToolkit = result.items[2];
2713 expect(githubToolkit.slug).toBe('github');
2714 expect(githubToolkit.connection?.isActive).toBe(false);
2715 expect(githubToolkit.connection?.authConfig).toBeNull();
2716 expect(githubToolkit.connection?.connectedAccount).toBeUndefined();
2717 });
2718
2719 it('should transform toolkit connection state correctly for no-auth toolkit', async () => {
2720 const noAuthToolkitsResponse = {
2721 items: [
2722 {
2723 slug: 'codeinterpreter',
2724 name: 'Code Interpreter',
2725 meta: {
2726 logo: 'https://example.com/codeinterpreter-logo.png',
2727 },
2728 is_no_auth: true,
2729 connected_account: null,
2730 },
2731 ],
2732 next_cursor: undefined,
2733 total_pages: 1,
2734 };
2735
2736 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(noAuthToolkitsResponse);
2737
2738 const session = await toolRouter.create(userId);
2739 const result = await session.toolkits();
2740
2741 const codeinterpreterToolkit = result.items[0];
2742 expect(codeinterpreterToolkit.slug).toBe('codeinterpreter');
2743 expect(codeinterpreterToolkit.name).toBe('Code Interpreter');
2744 expect(codeinterpreterToolkit.isNoAuth).toBe(true);
2745 expect(codeinterpreterToolkit.connection).toBeUndefined();
2746 });
2747
2748 it('should handle empty toolkits response', async () => {
2749 const emptyResponse = {
2750 items: [],
2751 next_cursor: undefined,
2752 total_pages: 0,
2753 };
2754
2755 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(emptyResponse);
2756
2757 const session = await toolRouter.create(userId);
2758 const result = await session.toolkits();
2759
2760 expect(result.items).toHaveLength(0);
2761 expect(result.cursor).toBeUndefined();
2762 expect(result.totalPages).toBe(0);
2763 });
2764
2765 it('should handle pagination through multiple pages', async () => {
2766 const firstPageResponse = {
2767 items: mockToolkitsResponse.items.slice(0, 2),
2768 next_cursor: 'cursor_page2',
2769 total_pages: 2,
2770 };
2771
2772 const secondPageResponse = {
2773 items: mockToolkitsResponse.items.slice(2),
2774 next_cursor: undefined,
2775 total_pages: 2,
2776 };
2777
2778 mockClient.toolRouter.session.toolkits
2779 .mockResolvedValueOnce(firstPageResponse)
2780 .mockResolvedValueOnce(secondPageResponse);
2781
2782 const session = await toolRouter.create(userId);
2783
2784 // Fetch first page
2785 const page1 = await session.toolkits({ limit: 2 });
2786 expect(page1.items).toHaveLength(2);
2787 expect(page1.cursor).toBe('cursor_page2');
2788
2789 // Fetch second page
2790 const page2 = await session.toolkits({
2791 limit: 2,
2792 cursor: page1.cursor,
2793 });
2794 expect(page2.items).toHaveLength(1);
2795 expect(page2.cursor).toBeUndefined();
2796 });
2797
2798 it('should handle API errors', async () => {
2799 const apiError = new Error('Failed to fetch toolkits');
2800 mockClient.toolRouter.session.toolkits.mockRejectedValueOnce(apiError);
2801
2802 const session = await toolRouter.create(userId);
2803
2804 await expect(session.toolkits()).rejects.toThrow('Failed to fetch toolkits');
2805 });
2806
2807 it('should handle malformed response data gracefully with undefined values', async () => {
2808 const malformedResponse = {
2809 items: [
2810 {
2811 slug: 'gmail',
2812 // Missing required fields like name, meta, is_no_auth
2813 },
2814 ],
2815 next_cursor: undefined,
2816 total_pages: 1,
2817 };
2818
2819 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(malformedResponse);
2820
2821 const session = await toolRouter.create(userId);
2822
2823 // The code handles malformed data gracefully with undefined values
2824 const result = await session.toolkits();
2825 expect(result.items).toHaveLength(1);
2826 expect(result.items[0].slug).toBe('gmail');
2827 expect(result.items[0].name).toBeUndefined();
2828 expect(result.items[0].logo).toBeUndefined();
2829 expect(result.items[0].isNoAuth).toBeUndefined();
2830 });
2831
2832 it('should throw validation error for invalid options', async () => {
2833 const session = await toolRouter.create(userId);
2834
2835 // Invalid options should throw a validation error
2836 await expect(
2837 session.toolkits({
2838 limit: 'invalid' as unknown as number, // Invalid type
2839 })
2840 ).rejects.toThrow();
2841 });
2842 });
2843
2844 describe('search function', () => {
2845 const userId = 'user_123';
2846 const sessionId = 'session_123';
2847
2848 const mockSearchResponse = {
2849 success: true,
2850 error: null,
2851 results: [
2852 {
2853 index: 1,
2854 use_case: 'send emails',
2855 primary_tool_slugs: ['GMAIL_SEND_EMAIL'],
2856 related_tool_slugs: [],
2857 toolkits: ['gmail'],
2858 },
2859 ],
2860 tool_schemas: {
2861 GMAIL_SEND_EMAIL: {
2862 tool_slug: 'GMAIL_SEND_EMAIL',
2863 toolkit: 'gmail',
2864 description: 'Send an email',
2865 hasFullSchema: true,
2866 input_schema: {},
2867 output_schema: {},
2868 },
2869 },
2870 toolkit_connection_statuses: [
2871 {
2872 toolkit: 'gmail',
2873 description: 'Gmail',
2874 has_active_connection: false,
2875 status_message: 'No connection',
2876 },
2877 ],
2878 next_steps_guidance: ['Connect Gmail'],
2879 session: {
2880 id: 'trs_123',
2881 generate_id: false,
2882 instructions: 'Reuse session',
2883 },
2884 time_info: {
2885 current_time_utc: '2025-03-09T12:00:00.000Z',
2886 current_time_utc_epoch_seconds: 1741521600,
2887 message: 'UTC',
2888 },
2889 };
2890
2891 it('should call search with correct params and return camelCase response', async () => {
2892 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2893 mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);
2894
2895 const session = await toolRouter.create(userId);
2896 const result = await session.search({ query: 'send emails' });
2897
2898 expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(
2899 sessionId,
2900 {
2901 queries: [{ use_case: 'send emails' }],
2902 },
2903 undefined
2904 );
2905 expect(result.success).toBe(true);
2906 expect(result.results[0].useCase).toBe('send emails');
2907 expect(result.results[0].primaryToolSlugs).toEqual(['GMAIL_SEND_EMAIL']);
2908 expect(result.toolSchemas.GMAIL_SEND_EMAIL.toolSlug).toBe('GMAIL_SEND_EMAIL');
2909 expect(result.nextStepsGuidance).toEqual(['Connect Gmail']);
2910 expect(result.session.generateId).toBe(false);
2911 expect(result.timeInfo.currentTimeUtcEpochSeconds).toBe(1741521600);
2912 });
2913
2914 it('should pass toolkits filter when provided', async () => {
2915 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2916 mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);
2917
2918 const session = await toolRouter.create(userId);
2919 await session.search({ query: 'send emails', toolkits: ['gmail', 'slack'] });
2920
2921 expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(
2922 sessionId,
2923 {
2924 queries: [{ use_case: 'send emails' }],
2925 toolkits: ['gmail', 'slack'],
2926 },
2927 undefined
2928 );
2929 });
2930
2931 it('should pass inline custom tools to search', async () => {
2932 const grepTool = createCustomTool('GREP', {
2933 name: 'Grep',
2934 description: 'Search local text',
2935 preload: true,
2936 inputParams: z.object({ pattern: z.string() }),
2937 execute: vi.fn(async () => ({ matches: [] })),
2938 });
2939 mockClient.toolRouter.session.create.mockResolvedValueOnce({
2940 ...mockSessionCreateResponse,
2941 experimental: {
2942 custom_tools: [
2943 {
2944 slug: 'LOCAL_GREP',
2945 original_slug: 'GREP',
2946 extends_toolkit: null,
2947 },
2948 ],
2949 },
2950 });
2951 mockClient.toolRouter.session.search.mockResolvedValueOnce(mockSearchResponse);
2952
2953 const session = await toolRouter.create(userId, {
2954 experimental: { customTools: [grepTool] },
2955 });
2956 await session.search({ query: 'search local text' });
2957
2958 expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(
2959 sessionId,
2960 {
2961 queries: [{ use_case: 'search local text' }],
2962 experimental: {
2963 custom_tools: [
2964 expect.objectContaining({
2965 slug: 'GREP',
2966 preload: true,
2967 }),
2968 ],
2969 },
2970 },
2971 undefined
2972 );
2973 });
2974
2975 it('should return the Instant account allowlist on toolkit connection statuses', async () => {
2976 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
2977 mockClient.toolRouter.session.search.mockResolvedValueOnce({
2978 ...mockSearchResponse,
2979 toolkit_connection_statuses: [
2980 {
2981 toolkit: 'exa',
2982 description: 'Exa',
2983 has_active_connection: true,
2984 instant_account: { allowed_tool_slugs: ['EXA_SEARCH'] },
2985 status_message: 'Connected via the Composio Instant account.',
2986 },
2987 ],
2988 });
2989
2990 const session = await toolRouter.create(userId);
2991 const result = await session.search({ query: 'search the web' });
2992
2993 expect(result.toolkitConnectionStatuses[0].instantAccount).toEqual({
2994 allowedToolSlugs: ['EXA_SEARCH'],
2995 });
2996 });
2997
2998 it('should propagate search API errors', async () => {
2999 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3000 mockClient.toolRouter.session.search.mockRejectedValueOnce(new Error('Search failed'));
3001
3002 const session = await toolRouter.create(userId);
3003
3004 await expect(session.search({ query: 'send emails' })).rejects.toThrow('Search failed');
3005 });
3006 });
3007
3008 describe('execute function', () => {
3009 const userId = 'user_123';
3010 const sessionId = 'session_123';
3011
3012 const mockExecuteResponse = {
3013 result_type: 'completed',
3014 data: { tool_slug: 'GMAIL_SEND_EMAIL', id: 'msg_123' },
3015 error: null,
3016 log_id: 'log_abc',
3017 };
3018
3019 it('should call execute with correct params and return camelCase response', async () => {
3020 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3021 mockClient.toolRouter.session.execute.mockResolvedValueOnce(mockExecuteResponse);
3022
3023 const session = await toolRouter.create(userId);
3024 const result = await session.execute('GMAIL_SEND_EMAIL', {
3025 to: 'user@example.com',
3026 subject: 'Hi',
3027 body: 'Hello',
3028 });
3029
3030 expect(mockClient.toolRouter.session.execute).toHaveBeenCalledWith(
3031 sessionId,
3032 {
3033 tool_slug: 'GMAIL_SEND_EMAIL',
3034 arguments: { to: 'user@example.com', subject: 'Hi', body: 'Hello' },
3035 },
3036 { maxRetries: 0 }
3037 );
3038 expect(result.data).toEqual({ tool_slug: 'GMAIL_SEND_EMAIL', id: 'msg_123' });
3039 expect(result.error).toBeNull();
3040 expect(result.logId).toBe('log_abc');
3041 });
3042
3043 it('returns the Instant charge when the API includes one', async () => {
3044 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3045 mockClient.toolRouter.session.execute.mockResolvedValueOnce({
3046 ...mockExecuteResponse,
3047 instant_charge: { amount: '0.01', currency: 'USD' },
3048 });
3049
3050 const session = await toolRouter.create(userId, {
3051 instant: { returnInstantCharge: true },
3052 });
3053 const result = await session.execute('GMAIL_SEND_EMAIL');
3054
3055 expect(result.instantCharge).toEqual({ amount: '0.01', currency: 'USD' });
3056 });
3057
3058 it('wraps execute API errors with the tool context', async () => {
3059 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3060 const cause = new Error('Execute failed');
3061 mockClient.toolRouter.session.execute.mockRejectedValueOnce(cause);
3062
3063 const session = await toolRouter.create(userId);
3064 const error = await session.execute('GMAIL_SEND_EMAIL').catch(e => e);
3065
3066 expect(error).toBeInstanceOf(ComposioToolExecutionError);
3067 expect(error.message).toBe('Error executing the tool GMAIL_SEND_EMAIL: Execute failed');
3068 expect(error.cause).toBe(cause);
3069 });
3070
3071 it('surfaces the server details of a rejected execute', async () => {
3072 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3073 mockClient.toolRouter.session.execute.mockRejectedValueOnce(
3074 new APIError(
3075 410,
3076 {
3077 error: {
3078 message: 'Toolkit version 20250101_00 is retired',
3079 code: 1410,
3080 slug: 'TOOLKIT_VERSION_RETIRED',
3081 status: 410,
3082 suggested_fix: 'Pin 20250909_00',
3083 },
3084 },
3085 undefined,
3086 new Headers({ 'x-request-id': 'req_router_410' })
3087 )
3088 );
3089
3090 const session = await toolRouter.create(userId);
3091 const error = await session.execute('GMAIL_SEND_EMAIL').catch(e => e);
3092
3093 expect(error).toBeInstanceOf(ComposioToolExecutionError);
3094 expect(error.message).toBe(
3095 'Error executing the tool GMAIL_SEND_EMAIL: Toolkit version 20250101_00 is retired'
3096 );
3097 expect(error.statusCode).toBe(410);
3098 expect(error.apiErrorCode).toBe(1410);
3099 expect(error.requestId).toBe('req_router_410');
3100 expect(error.possibleFixes).toEqual(['Pin 20250909_00']);
3101 });
3102
3103 it('should default arguments to empty object when omitted', async () => {
3104 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3105 mockClient.toolRouter.session.execute.mockResolvedValueOnce(mockExecuteResponse);
3106
3107 const session = await toolRouter.create(userId);
3108 await session.execute('HACKERNEWS_GET_USER');
3109
3110 expect(mockClient.toolRouter.session.execute).toHaveBeenCalledWith(
3111 sessionId,
3112 {
3113 tool_slug: 'HACKERNEWS_GET_USER',
3114 arguments: {},
3115 },
3116 { maxRetries: 0 }
3117 );
3118 });
3119
3120 it('should pass account option to session execute', async () => {
3121 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3122 mockClient.toolRouter.session.execute.mockResolvedValueOnce(mockExecuteResponse);
3123
3124 const session = await toolRouter.create(userId);
3125 await session.execute('GMAIL_SEND_EMAIL', { to: 'user@example.com' }, { account: 'work' });
3126
3127 expect(mockClient.toolRouter.session.execute).toHaveBeenCalledWith(
3128 sessionId,
3129 {
3130 tool_slug: 'GMAIL_SEND_EMAIL',
3131 arguments: { to: 'user@example.com' },
3132 account: 'work',
3133 },
3134 { maxRetries: 0 }
3135 );
3136 });
3137
3138 it('should pass inline custom tools to remote execute when custom tools are bound', async () => {
3139 const grepTool = createCustomTool('GREP', {
3140 name: 'Grep',
3141 description: 'Search local text',
3142 inputParams: z.object({ pattern: z.string() }),
3143 execute: vi.fn(async () => ({ matches: [] })),
3144 });
3145 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3146 ...mockSessionCreateResponse,
3147 experimental: {
3148 custom_tools: [
3149 {
3150 slug: 'LOCAL_GREP',
3151 original_slug: 'GREP',
3152 extends_toolkit: null,
3153 },
3154 ],
3155 },
3156 });
3157 mockClient.toolRouter.session.execute.mockResolvedValueOnce(mockExecuteResponse);
3158
3159 const session = await toolRouter.create(userId, {
3160 experimental: { customTools: [grepTool] },
3161 });
3162 await session.execute('GMAIL_SEND_EMAIL', { to: 'user@example.com' });
3163
3164 expect(mockClient.toolRouter.session.execute).toHaveBeenCalledWith(
3165 sessionId,
3166 {
3167 tool_slug: 'GMAIL_SEND_EMAIL',
3168 arguments: { to: 'user@example.com' },
3169 experimental: {
3170 custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3171 },
3172 },
3173 { maxRetries: 0 }
3174 );
3175 });
3176 });
3177
3178 describe('executeMeta function', () => {
3179 const userId = 'user_123';
3180 const sessionId = 'session_123';
3181
3182 const mockExecuteMetaResponse = {
3183 result_type: 'completed',
3184 data: { results: [] },
3185 error: null,
3186 log_id: 'log_abc',
3187 };
3188
3189 it('should call executeMeta with correct params and return camelCase response', async () => {
3190 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3191 mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3192
3193 const session = await toolRouter.create(userId);
3194 const result = await session.executeMeta('COMPOSIO_SEARCH_TOOLS', {
3195 queries: [{ use_case: 'send an email' }],
3196 });
3197
3198 expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3199 sessionId,
3200 {
3201 slug: 'COMPOSIO_SEARCH_TOOLS',
3202 arguments: { queries: [{ use_case: 'send an email' }] },
3203 },
3204 { maxRetries: 0 }
3205 );
3206 expect(mockClient.toolRouter.session.execute).not.toHaveBeenCalled();
3207 expect(result).toEqual({
3208 data: { results: [] },
3209 error: null,
3210 logId: 'log_abc',
3211 resultType: 'completed',
3212 });
3213 });
3214
3215 it('should default arguments to empty object when omitted', async () => {
3216 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3217 mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3218
3219 const session = await toolRouter.create(userId);
3220 await session.executeMeta('COMPOSIO_MANAGE_CONNECTIONS');
3221
3222 expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3223 sessionId,
3224 { slug: 'COMPOSIO_MANAGE_CONNECTIONS', arguments: {} },
3225 { maxRetries: 0 }
3226 );
3227 });
3228
3229 it('wraps executeMeta API errors with the tool context', async () => {
3230 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3231 const cause = new Error('Execute failed');
3232 mockClient.toolRouter.session.executeMeta.mockRejectedValueOnce(cause);
3233
3234 const session = await toolRouter.create(userId);
3235 const error = await session.executeMeta('COMPOSIO_SEARCH_TOOLS').catch(e => e);
3236
3237 expect(error).toBeInstanceOf(ComposioToolExecutionError);
3238 expect(error.message).toBe('Error executing the tool COMPOSIO_SEARCH_TOOLS: Execute failed');
3239 expect(error.cause).toBe(cause);
3240 });
3241
3242 it('should pass inline custom tools to executeMeta when custom tools are bound', async () => {
3243 const grepTool = createCustomTool('GREP', {
3244 name: 'Grep',
3245 description: 'Search local text',
3246 inputParams: z.object({ pattern: z.string() }),
3247 execute: vi.fn(async () => ({ matches: [] })),
3248 });
3249 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3250 ...mockSessionCreateResponse,
3251 experimental: {
3252 custom_tools: [
3253 {
3254 slug: 'LOCAL_GREP',
3255 original_slug: 'GREP',
3256 extends_toolkit: null,
3257 },
3258 ],
3259 },
3260 });
3261 mockClient.toolRouter.session.executeMeta.mockResolvedValueOnce(mockExecuteMetaResponse);
3262
3263 const session = await toolRouter.create(userId, {
3264 experimental: { customTools: [grepTool] },
3265 });
3266 await session.executeMeta('COMPOSIO_SEARCH_TOOLS', { queries: [{ use_case: 'grep' }] });
3267
3268 expect(mockClient.toolRouter.session.executeMeta).toHaveBeenCalledWith(
3269 sessionId,
3270 {
3271 slug: 'COMPOSIO_SEARCH_TOOLS',
3272 arguments: { queries: [{ use_case: 'grep' }] },
3273 experimental: {
3274 custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3275 },
3276 },
3277 { maxRetries: 0 }
3278 );
3279 });
3280 });
3281
3282 describe('tools function', () => {
3283 const userId = 'user_123';
3284 const sessionId = 'session_123';
3285 const validSessionTool = { slug: 'COMPOSIO_SEARCH_TOOLS', name: 'Search tools' };
3286
3287 const mockToolsWithValidSessionTool = () => {
3288 vi.mocked(Tools).mockImplementationOnce(function () {
3289 return {
3290 getRawComposioTools: vi.fn().mockResolvedValue([{ slug: 'GMAIL_FETCH_EMAILS' }]),
3291 getRawToolRouterSessionTools: vi.fn().mockResolvedValue([validSessionTool]),
3292 wrapToolsForToolRouter: vi.fn().mockReturnValue('mocked-wrapped-tools'),
3293 };
3294 });
3295 };
3296
3297 beforeEach(() => {
3298 // Reset the Tools mock before each test
3299 vi.clearAllMocks();
3300 vi.mocked(Tools).mockImplementation(function () {
3301 return {
3302 getRawComposioTools: vi.fn().mockResolvedValue([{ slug: 'GMAIL_FETCH_EMAILS' }]),
3303 getRawToolRouterSessionTools: vi
3304 .fn()
3305 .mockResolvedValue([{ slug: 'COMPOSIO_SEARCH_TOOLS' }]),
3306 wrapToolsForToolRouter: vi.fn().mockReturnValue('mocked-wrapped-tools'),
3307 };
3308 });
3309 });
3310
3311 it('should fetch and wrap tools without modifiers', async () => {
3312 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3313
3314 const session = await toolRouter.create(userId);
3315 const tools = await session.tools();
3316
3317 expect(Tools).toHaveBeenCalledWith(mockClient, {
3318 provider: mockProvider,
3319 apiKey: 'test-api-key',
3320 });
3321
3322 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
3323 expect(toolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3324 sessionId,
3325 undefined,
3326 undefined
3327 );
3328 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3329 sessionId,
3330 [{ slug: 'COMPOSIO_SEARCH_TOOLS' }],
3331 undefined
3332 );
3333
3334 expect(tools).toBe('mocked-wrapped-tools');
3335 });
3336
3337 it('should fetch and wrap tools with modifiers', async () => {
3338 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3339
3340 const modifiers = {
3341 modifySchema: vi.fn(({ schema }) => ({
3342 ...schema,
3343 description: 'Modified description',
3344 })),
3345 beforeExecute: vi.fn(),
3346 };
3347 mockToolsWithValidSessionTool();
3348
3349 const session = await toolRouter.create(userId);
3350 const tools = await session.tools(modifiers);
3351
3352 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
3353 expect(toolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3354 sessionId,
3355 undefined,
3356 undefined
3357 );
3358 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3359 sessionId,
3360 [{ ...validSessionTool, description: 'Modified description' }],
3361 modifiers,
3362 [validSessionTool]
3363 );
3364
3365 expect(tools).toBe('mocked-wrapped-tools');
3366 });
3367
3368 it('should include preloaded tools returned by the session tools endpoint', async () => {
3369 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3370 ...mockSessionCreateResponse,
3371 config: {
3372 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
3373 },
3374 });
3375
3376 vi.mocked(Tools).mockImplementation(function () {
3377 return {
3378 getRawComposioTools: vi.fn().mockResolvedValue([{ slug: 'GMAIL_FETCH_EMAILS' }]),
3379 getRawToolRouterSessionTools: vi
3380 .fn()
3381 .mockResolvedValue([
3382 { slug: 'COMPOSIO_SEARCH_TOOLS' },
3383 { slug: 'GMAIL_FETCH_EMAILS', toolkit: { slug: 'gmail', name: 'Gmail' } },
3384 ]),
3385 wrapToolsForToolRouter: vi.fn().mockReturnValue('mocked-wrapped-tools'),
3386 };
3387 });
3388
3389 const session = await toolRouter.create(userId, {
3390 toolkits: ['gmail'],
3391 preload: { tools: ['GMAIL_FETCH_EMAILS'] },
3392 });
3393 const tools = await session.tools();
3394
3395 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
3396 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3397 sessionId,
3398 [
3399 { slug: 'COMPOSIO_SEARCH_TOOLS' },
3400 { slug: 'GMAIL_FETCH_EMAILS', toolkit: { slug: 'gmail', name: 'Gmail' } },
3401 ],
3402 undefined
3403 );
3404 expect(tools).toBe('mocked-wrapped-tools');
3405 });
3406
3407 it('should include custom tools with preload enabled locally', async () => {
3408 const executeGrep = vi.fn(async ({ pattern }: { pattern: string }) => ({
3409 matches: [pattern],
3410 }));
3411 const grepTool = createCustomTool('GREP', {
3412 name: 'Grep',
3413 description: 'Search local text',
3414 preload: true,
3415 inputParams: z.object({
3416 pattern: z.string().describe('Pattern to search for'),
3417 }),
3418 execute: executeGrep,
3419 });
3420
3421 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3422 ...mockSessionCreateResponse,
3423 tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
3424 experimental: {
3425 custom_tools: [
3426 {
3427 slug: 'SERVER_GREP',
3428 original_slug: 'GREP',
3429 extends_toolkit: null,
3430 },
3431 ],
3432 },
3433 });
3434 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3435
3436 const session = await toolRouter.create(userId, {
3437 experimental: { customTools: [grepTool] },
3438 });
3439 const tools = await session.tools();
3440
3441 expect(mockProvider.wrapTools).toHaveBeenCalledTimes(1);
3442 const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{
3443 slug: string;
3444 description?: string;
3445 toolkit?: { slug: string; name: string };
3446 }>;
3447 expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'SERVER_GREP']);
3448 expect(wrappedTools[1].description).toContain(DIRECT_CUSTOM_TOOL_DESCRIPTION_PREFIX);
3449 expect(wrappedTools[1].toolkit).toEqual({ slug: 'custom', name: 'Custom' });
3450 expect(tools).toBe('mocked-custom-tools');
3451
3452 const routingExecute = mockProvider.wrapTools.mock.calls[0][1] as (
3453 toolSlug: string,
3454 input: Record<string, unknown>
3455 ) => Promise<unknown>;
3456 const result = await routingExecute('SERVER_GREP', { pattern: 'needle' });
3457 expect(result).toEqual({
3458 data: { matches: ['needle'] },
3459 error: null,
3460 successful: true,
3461 });
3462 expect(executeGrep).toHaveBeenCalledWith({ pattern: 'needle' }, expect.anything());
3463 expect(mockClient.toolRouter.session.execute).not.toHaveBeenCalled();
3464 });
3465
3466 it('should pass inline custom tools when routing remote provider executions', async () => {
3467 const grepTool = createCustomTool('GREP', {
3468 name: 'Grep',
3469 description: 'Search local text',
3470 inputParams: z.object({ pattern: z.string() }),
3471 execute: vi.fn(async () => ({ matches: [] })),
3472 });
3473 const executeSessionTool = vi.fn().mockResolvedValue({
3474 data: { ok: true },
3475 error: null,
3476 successful: true,
3477 });
3478 vi.mocked(Tools).mockImplementation(function () {
3479 return {
3480 getRawToolRouterSessionTools: vi
3481 .fn()
3482 .mockResolvedValue([
3483 { slug: 'COMPOSIO_SEARCH_TOOLS' },
3484 { slug: 'GMAIL_SEND_EMAIL', toolkit: { slug: 'gmail', name: 'Gmail' } },
3485 ]),
3486 executeSessionTool,
3487 };
3488 });
3489 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3490 ...mockSessionCreateResponse,
3491 experimental: {
3492 custom_tools: [
3493 {
3494 slug: 'LOCAL_GREP',
3495 original_slug: 'GREP',
3496 extends_toolkit: null,
3497 },
3498 ],
3499 },
3500 });
3501 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3502
3503 const session = await toolRouter.create(userId, {
3504 experimental: { customTools: [grepTool] },
3505 });
3506 await session.tools();
3507 const routingExecute = mockProvider.wrapTools.mock.calls[0][1] as (
3508 toolSlug: string,
3509 input: Record<string, unknown>
3510 ) => Promise<unknown>;
3511 await routingExecute('GMAIL_SEND_EMAIL', { to: 'user@example.com' });
3512
3513 expect(executeSessionTool).toHaveBeenCalledWith(
3514 'GMAIL_SEND_EMAIL',
3515 { sessionId, arguments: { to: 'user@example.com' } },
3516 undefined,
3517 { slug: 'GMAIL_SEND_EMAIL', toolkit: { slug: 'gmail', name: 'Gmail' } },
3518 {
3519 experimental: {
3520 custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3521 },
3522 }
3523 );
3524 });
3525
3526 it('should pass inline custom tools when routing remote multi-execute batches', async () => {
3527 const grepTool = createCustomTool('GREP', {
3528 name: 'Grep',
3529 description: 'Search local text',
3530 inputParams: z.object({ pattern: z.string() }),
3531 execute: vi.fn(async () => ({ matches: [] })),
3532 });
3533 const executeSessionTool = vi.fn().mockResolvedValue({
3534 data: { results: [] },
3535 error: null,
3536 successful: true,
3537 });
3538 const multiExecuteTool = { slug: 'COMPOSIO_MULTI_EXECUTE_TOOL' };
3539 vi.mocked(Tools).mockImplementation(function () {
3540 return {
3541 getRawToolRouterSessionTools: vi
3542 .fn()
3543 .mockResolvedValue([{ slug: 'COMPOSIO_SEARCH_TOOLS' }, multiExecuteTool]),
3544 executeSessionTool,
3545 };
3546 });
3547 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3548 ...mockSessionCreateResponse,
3549 experimental: {
3550 custom_tools: [
3551 {
3552 slug: 'LOCAL_GREP',
3553 original_slug: 'GREP',
3554 extends_toolkit: null,
3555 },
3556 ],
3557 },
3558 });
3559 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3560
3561 const session = await toolRouter.create(userId, {
3562 experimental: { customTools: [grepTool] },
3563 });
3564 await session.tools();
3565 const routingExecute = mockProvider.wrapTools.mock.calls[0][1] as (
3566 toolSlug: string,
3567 input: Record<string, unknown>
3568 ) => Promise<unknown>;
3569 const input = { tools: [{ tool_slug: 'GMAIL_SEND_EMAIL', arguments: { to: 'a@b.com' } }] };
3570 await routingExecute('COMPOSIO_MULTI_EXECUTE_TOOL', input);
3571
3572 expect(executeSessionTool).toHaveBeenCalledWith(
3573 'COMPOSIO_MULTI_EXECUTE_TOOL',
3574 { sessionId, arguments: input },
3575 undefined,
3576 multiExecuteTool,
3577 {
3578 experimental: {
3579 custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3580 },
3581 }
3582 );
3583 });
3584
3585 it('should not expose custom tools unless SDK preload selects them', async () => {
3586 const grepTool = createCustomTool('GREP', {
3587 name: 'Grep',
3588 description: 'Search local text',
3589 inputParams: z.object({
3590 pattern: z.string(),
3591 }),
3592 execute: vi.fn(async () => ({ matches: [] })),
3593 });
3594
3595 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3596 ...mockSessionCreateResponse,
3597 tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
3598 experimental: {
3599 custom_tools: [
3600 {
3601 slug: 'LOCAL_GREP',
3602 original_slug: 'GREP',
3603 extends_toolkit: null,
3604 },
3605 ],
3606 },
3607 });
3608 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3609
3610 const session = await toolRouter.create(userId, {
3611 experimental: { customTools: [grepTool] },
3612 });
3613 await session.tools();
3614
3615 const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
3616 expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS']);
3617 });
3618
3619 it('should expose custom tools by default for preload all', async () => {
3620 const grepTool = createCustomTool('GREP', {
3621 name: 'Grep',
3622 description: 'Search local text',
3623 inputParams: z.object({
3624 pattern: z.string(),
3625 }),
3626 execute: vi.fn(async () => ({ matches: [] })),
3627 });
3628
3629 mockClient.toolRouter.session.create.mockResolvedValueOnce({
3630 ...mockSessionCreateResponse,
3631 tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
3632 experimental: {
3633 custom_tools: [
3634 {
3635 slug: 'LOCAL_GREP',
3636 original_slug: 'GREP',
3637 extends_toolkit: null,
3638 },
3639 ],
3640 },
3641 });
3642 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
3643
3644 const session = await toolRouter.create(userId, {
3645 preload: { tools: 'all' },
3646 experimental: { customTools: [grepTool] },
3647 });
3648 await session.tools();
3649
3650 const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
3651 expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
3652 });
3653
3654 it('should handle tools fetching errors', async () => {
3655 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3656
3657 vi.mocked(Tools).mockImplementation(function () {
3658 return {
3659 getRawComposioTools: vi.fn().mockRejectedValue(new Error('Failed to fetch tools')),
3660 getRawToolRouterSessionTools: vi
3661 .fn()
3662 .mockRejectedValue(new Error('Failed to fetch tools')),
3663 wrapToolsForToolRouter: vi.fn().mockReturnValue('mocked-wrapped-tools'),
3664 };
3665 });
3666
3667 const session = await toolRouter.create(userId);
3668
3669 await expect(session.tools()).rejects.toThrow('Failed to fetch tools');
3670 });
3671
3672 it('should call tools function multiple times with different modifiers', async () => {
3673 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3674
3675 const modifier1 = { modifySchema: vi.fn(({ schema }) => schema) };
3676 const modifier2 = { modifySchema: vi.fn(({ schema }) => schema) };
3677 mockToolsWithValidSessionTool();
3678 mockToolsWithValidSessionTool();
3679
3680 const session = await toolRouter.create(userId);
3681
3682 // Each call to session.tools() creates a new Tools instance
3683 // So we need to check that Tools was called twice and each instance's methods were called
3684 await session.tools(modifier1);
3685 await session.tools(modifier2);
3686
3687 expect(Tools).toHaveBeenCalledTimes(2);
3688
3689 const firstToolsInstance = vi.mocked(Tools).mock.results[0].value;
3690 expect(firstToolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3691 sessionId,
3692 undefined,
3693 undefined
3694 );
3695 expect(firstToolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3696 sessionId,
3697 [validSessionTool],
3698 modifier1,
3699 [validSessionTool]
3700 );
3701
3702 const secondToolsInstance = vi.mocked(Tools).mock.results[1].value;
3703 expect(secondToolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3704 sessionId,
3705 undefined,
3706 undefined
3707 );
3708 expect(secondToolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3709 sessionId,
3710 [validSessionTool],
3711 modifier2,
3712 [validSessionTool]
3713 );
3714 });
3715
3716 it('should use tool slugs from session response', async () => {
3717 const customResponse = {
3718 ...mockSessionCreateResponse,
3719 session_id: 'custom_session_123',
3720 tool_router_tools: ['CUSTOM_TOOL_1', 'CUSTOM_TOOL_2'],
3721 };
3722
3723 mockClient.toolRouter.session.create.mockResolvedValueOnce(customResponse);
3724
3725 const newSession = await toolRouter.create(userId);
3726 await newSession.tools();
3727
3728 expect(Tools).toHaveBeenCalledWith(mockClient, {
3729 provider: mockProvider,
3730 apiKey: 'test-api-key',
3731 });
3732 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
3733 expect(toolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3734 'custom_session_123',
3735 undefined,
3736 undefined
3737 );
3738 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3739 'custom_session_123',
3740 [{ slug: 'COMPOSIO_SEARCH_TOOLS' }],
3741 undefined
3742 );
3743 });
3744
3745 it('should handle empty tool router tools array', async () => {
3746 const emptyToolsResponse = {
3747 ...mockSessionCreateResponse,
3748 session_id: 'empty_session_123',
3749 tool_router_tools: [],
3750 };
3751
3752 mockClient.toolRouter.session.create.mockResolvedValueOnce(emptyToolsResponse);
3753
3754 const session = await toolRouter.create(userId);
3755 await session.tools();
3756
3757 expect(Tools).toHaveBeenCalledWith(mockClient, {
3758 provider: mockProvider,
3759 apiKey: 'test-api-key',
3760 });
3761 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
3762 expect(toolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
3763 'empty_session_123',
3764 undefined,
3765 undefined
3766 );
3767 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
3768 'empty_session_123',
3769 [{ slug: 'COMPOSIO_SEARCH_TOOLS' }],
3770 undefined
3771 );
3772 });
3773 });
3774
3775 describe('integration tests', () => {
3776 const userId = 'user_123';
3777
3778 it('should create a complete session and use all functions', async () => {
3779 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
3780 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
3781 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
3782
3783 // Create session
3784 const session = await toolRouter.create(userId, {
3785 toolkits: ['gmail', 'slack'],
3786 manageConnections: true,
3787 });
3788
3789 expect(session.sessionId).toBe('session_123');
3790 expect(session.mcp.url).toBe(
3791 'https://api.composio.dev/api/v3/tool_router/session/session_123'
3792 );
3793
3794 // Use authorize function
3795 const connection = await session.authorize('gmail');
3796 expect(connection.id).toBe('conn_456');
3797
3798 // Use toolkits function
3799 const toolkits = await session.toolkits();
3800 expect(toolkits.items).toHaveLength(3);
3801
3802 // Use tools function
3803 const tools = await session.tools();
3804 expect(tools).toBe('mocked-wrapped-tools');
3805
3806 // Verify all API calls were made
3807 expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
3808 expect(mockClient.toolRouter.session.link).toHaveBeenCalledTimes(1);
3809 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledTimes(1);
3810 });
3811
3812 it('should handle multiple sessions independently', async () => {
3813 const session1Response = {
3814 ...mockSessionCreateResponse,
3815 session_id: 'session_1',
3816 };
3817
3818 const session2Response = {
3819 ...mockSessionCreateResponse,
3820 session_id: 'session_2',
3821 };
3822
3823 mockClient.toolRouter.session.create
3824 .mockResolvedValueOnce(session1Response)
3825 .mockResolvedValueOnce(session2Response);
3826
3827 mockClient.toolRouter.session.toolkits.mockResolvedValue(mockToolkitsResponse);
3828
3829 const session1 = await toolRouter.create('user_1');
3830 const session2 = await toolRouter.create('user_2');
3831
3832 expect(session1.sessionId).toBe('session_1');
3833 expect(session2.sessionId).toBe('session_2');
3834
3835 await session1.toolkits();
3836 await session2.toolkits();
3837
3838 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
3839 'session_1',
3840 {
3841 cursor: undefined,
3842 limit: undefined,
3843 toolkits: undefined,
3844 is_connected: undefined,
3845 },
3846 undefined
3847 );
3848 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
3849 'session_2',
3850 {
3851 cursor: undefined,
3852 limit: undefined,
3853 toolkits: undefined,
3854 is_connected: undefined,
3855 },
3856 undefined
3857 );
3858 });
3859
3860 it('should handle rapid successive calls', async () => {
3861 mockClient.toolRouter.session.create.mockResolvedValue(mockSessionCreateResponse);
3862 mockClient.toolRouter.session.toolkits.mockResolvedValue(mockToolkitsResponse);
3863
3864 const session = await toolRouter.create(userId);
3865
3866 // Make multiple rapid calls
3867 const promises = [session.toolkits(), session.toolkits(), session.toolkits()];
3868
3869 const results = await Promise.all(promises);
3870
3871 expect(results).toHaveLength(3);
3872 results.forEach(result => {
3873 expect(result.items).toHaveLength(3);
3874 });
3875
3876 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledTimes(3);
3877 });
3878 });
3879
3880 describe('delete method', () => {
3881 it('should delete a session by ID and return a camelCase response', async () => {
3882 mockClient.toolRouter.session.delete.mockResolvedValueOnce({
3883 session_id: 'trs_delete_123',
3884 deleted: true,
3885 });
3886
3887 const result = await toolRouter.delete('trs_delete_123');
3888
3889 expect(mockClient.toolRouter.session.delete).toHaveBeenCalledWith(
3890 'trs_delete_123',
3891 undefined
3892 );
3893 expect(result).toEqual({
3894 sessionId: 'trs_delete_123',
3895 deleted: true,
3896 });
3897 });
3898
3899 it('should forward request options when deleting by ID', async () => {
3900 const requestOptions = { signal: new AbortController().signal };
3901 mockClient.toolRouter.session.delete.mockResolvedValueOnce({
3902 session_id: 'trs_delete_123',
3903 deleted: true,
3904 });
3905
3906 await toolRouter.delete('trs_delete_123', requestOptions);
3907
3908 expect(mockClient.toolRouter.session.delete).toHaveBeenCalledWith(
3909 'trs_delete_123',
3910 requestOptions
3911 );
3912 });
3913 });
3914
3915 describe('use method', () => {
3916 const sessionId = 'session_123';
3917
3918 it('should retrieve an existing session by ID', async () => {
3919 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
3920
3921 const session = await toolRouter.use(sessionId);
3922
3923 expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId, undefined);
3924 expect(mockClient.toolRouter.session.attach).not.toHaveBeenCalled();
3925 expect(mockClient.post).not.toHaveBeenCalled();
3926 expect(session).toHaveProperty('sessionId', 'session_123');
3927 expect(session).toHaveProperty('mcp');
3928 expect(session.mcp).toEqual({
3929 type: 'http',
3930 url: 'https://api.composio.dev/api/v3/tool_router/session/session_123',
3931 headers: {
3932 'x-api-key': 'test-api-key',
3933 },
3934 });
3935 expect(session).toHaveProperty('tools');
3936 expect(session).toHaveProperty('authorize');
3937 expect(session).toHaveProperty('toolkits');
3938 expect(session).toHaveProperty('delete');
3939 expect(session.preload.tools).toEqual(['GMAIL_FETCH_EMAILS']);
3940 expect(session.configVersion).toBe(7);
3941 expect(session.config).toEqual(mockSessionRetrieveResponse.config);
3942 expect(session.config.toolkits).toEqual({ enabled: ['gmail', 'slack', 'github'] });
3943 });
3944
3945 it('should attach custom tools when provided', async () => {
3946 const grepTool = createCustomTool('GREP', {
3947 name: 'Grep',
3948 description: 'Search local text',
3949 inputParams: z.object({ pattern: z.string() }),
3950 execute: vi.fn(async () => ({ matches: [] })),
3951 });
3952
3953 mockClient.toolRouter.session.attach.mockResolvedValueOnce({
3954 ...mockSessionRetrieveResponse,
3955 experimental: {
3956 custom_tools: [
3957 {
3958 slug: 'SERVER_GREP',
3959 original_slug: 'GREP',
3960 extends_toolkit: null,
3961 },
3962 ],
3963 },
3964 });
3965
3966 const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
3967
3968 expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(
3969 sessionId,
3970 {
3971 experimental: {
3972 custom_tools: [expect.objectContaining({ slug: 'GREP' })],
3973 },
3974 },
3975 undefined
3976 );
3977 expect(mockClient.toolRouter.session.attach.mock.calls[0][1].experimental).not.toHaveProperty(
3978 'custom_toolkits'
3979 );
3980 expect(mockClient.post).not.toHaveBeenCalled();
3981 expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
3982 expect(session.customTools()).toEqual([
3983 expect.objectContaining({
3984 slug: 'SERVER_GREP',
3985 name: 'Grep',
3986 }),
3987 ]);
3988 });
3989
3990 it('should attach local tools passed as localTools with the same wire payload', async () => {
3991 const grepTool = createCustomTool('GREP', {
3992 name: 'Grep',
3993 description: 'Search local text',
3994 inputParams: z.object({ pattern: z.string() }),
3995 execute: vi.fn(async () => ({ matches: [] })),
3996 });
3997 const attachResponse = {
3998 ...mockSessionRetrieveResponse,
3999 experimental: {
4000 custom_tools: [{ slug: 'LOCAL_GREP', original_slug: 'GREP', extends_toolkit: null }],
4001 },
4002 };
4003 mockClient.toolRouter.session.attach
4004 .mockResolvedValueOnce(attachResponse)
4005 .mockResolvedValueOnce(attachResponse);
4006
4007 const session = await toolRouter.use(sessionId, { localTools: [grepTool] });
4008 await toolRouter.use(sessionId, { customTools: [grepTool] });
4009
4010 const [[, localBody], [, customBody]] = mockClient.toolRouter.session.attach.mock.calls;
4011 expect(localBody).toEqual({
4012 experimental: { custom_tools: [expect.objectContaining({ slug: 'GREP' })] },
4013 });
4014 expect(customBody).toEqual(localBody);
4015 expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
4016 expect(session.localTools()).toEqual([expect.objectContaining({ slug: 'LOCAL_GREP' })]);
4017 expect(session.customTools()).toEqual(session.localTools());
4018 });
4019
4020 it.each([
4021 ['localTools or customTools', { localTools: [], customTools: [] }],
4022 ['localToolkits or customToolkits', { localToolkits: [], customToolkits: [] }],
4023 ])(
4024 'should reject passing both %s to use() without calling the API',
4025 async (fields, options) => {
4026 const error = await toolRouter.use(sessionId, options).catch(e => e);
4027
4028 expect(error).toBeInstanceOf(ValidationError);
4029 expect(error.message).toContain(`Pass either ${fields}, not both`);
4030 expect(mockClient.toolRouter.session.attach).not.toHaveBeenCalled();
4031 expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
4032 }
4033 );
4034
4035 it('should return a session with correct session ID', async () => {
4036 const customResponse = {
4037 ...mockSessionRetrieveResponse,
4038 config: {
4039 ...mockSessionRetrieveResponse.config,
4040 user_id: 'custom_user_456',
4041 },
4042 };
4043
4044 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);
4045
4046 const session = await toolRouter.use(sessionId);
4047
4048 expect(session.sessionId).toBe('session_123');
4049 // The tools function should be created with the session ID
4050 expect(session.tools).toBeDefined();
4051 });
4052
4053 it('should return a session with working tools function', async () => {
4054 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4055
4056 const session = await toolRouter.use(sessionId);
4057
4058 const tools = await session.tools();
4059
4060 expect(tools).toBe('mocked-wrapped-tools');
4061 expect(Tools).toHaveBeenCalled();
4062
4063 const toolsInstance = vi.mocked(Tools).mock.results[0].value;
4064 expect(toolsInstance.getRawToolRouterSessionTools).toHaveBeenCalledWith(
4065 sessionId,
4066 undefined,
4067 undefined
4068 );
4069 expect(toolsInstance.wrapToolsForToolRouter).toHaveBeenCalledWith(
4070 sessionId,
4071 [{ slug: 'COMPOSIO_SEARCH_TOOLS' }],
4072 undefined
4073 );
4074 });
4075
4076 it('should return a session with working authorize function', async () => {
4077 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4078 mockClient.toolRouter.session.link.mockResolvedValueOnce(mockLinkResponse);
4079
4080 const session = await toolRouter.use(sessionId);
4081
4082 const connectionRequest = await session.authorize('github');
4083
4084 expect(mockClient.toolRouter.session.link).toHaveBeenCalledWith(
4085 sessionId,
4086 {
4087 toolkit: 'github',
4088 },
4089 undefined
4090 );
4091 expect(connectionRequest).toHaveProperty('redirectUrl', 'https://composio.dev/auth/redirect');
4092 expect(connectionRequest).toHaveProperty('status', ConnectedAccountStatuses.INITIATED);
4093 });
4094
4095 it('should return a session with working toolkits function', async () => {
4096 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4097 mockClient.toolRouter.session.toolkits.mockResolvedValueOnce(mockToolkitsResponse);
4098
4099 const session = await toolRouter.use(sessionId);
4100
4101 const toolkitsResult = await session.toolkits();
4102
4103 expect(mockClient.toolRouter.session.toolkits).toHaveBeenCalledWith(
4104 sessionId,
4105 {
4106 cursor: undefined,
4107 limit: undefined,
4108 toolkits: undefined,
4109 is_connected: undefined,
4110 },
4111 undefined
4112 );
4113 expect(toolkitsResult.items).toHaveLength(3);
4114 expect(toolkitsResult.items[0].slug).toBe('gmail');
4115 });
4116
4117 it('should return a session with working delete function', async () => {
4118 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4119 mockClient.toolRouter.session.delete.mockResolvedValueOnce({
4120 session_id: sessionId,
4121 deleted: true,
4122 });
4123
4124 const session = await toolRouter.use(sessionId);
4125 const result = await session.delete();
4126
4127 expect(mockClient.toolRouter.session.delete).toHaveBeenCalledWith(sessionId, undefined);
4128 expect(result).toEqual({
4129 sessionId,
4130 deleted: true,
4131 });
4132 });
4133
4134 it('should attach custom tools and expose SDK-preloaded custom schemas', async () => {
4135 const grepTool = createCustomTool('GREP', {
4136 name: 'Grep',
4137 description: 'Search local text',
4138 preload: true,
4139 inputParams: z.object({ pattern: z.string() }),
4140 execute: vi.fn(async () => ({ matches: [] })),
4141 });
4142 mockClient.toolRouter.session.attach.mockResolvedValueOnce({
4143 ...mockSessionRetrieveResponse,
4144 tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
4145 experimental: {
4146 custom_tools: [
4147 {
4148 slug: 'LOCAL_GREP',
4149 original_slug: 'GREP',
4150 extends_toolkit: null,
4151 },
4152 ],
4153 },
4154 });
4155 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
4156
4157 const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
4158 await session.tools();
4159
4160 expect(mockClient.toolRouter.session.attach).toHaveBeenCalledWith(
4161 sessionId,
4162 {
4163 experimental: {
4164 custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],
4165 },
4166 },
4167 undefined
4168 );
4169 expect(mockClient.post).not.toHaveBeenCalled();
4170 expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
4171 const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
4172 expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
4173 });
4174
4175 it('should apply preload all from an attached session to custom tools in use()', async () => {
4176 const grepTool = createCustomTool('GREP', {
4177 name: 'Grep',
4178 description: 'Search local text',
4179 inputParams: z.object({ pattern: z.string() }),
4180 execute: vi.fn(async () => ({ matches: [] })),
4181 });
4182 mockClient.toolRouter.session.attach.mockResolvedValueOnce({
4183 ...mockSessionRetrieveResponse,
4184 tool_router_tools: ['COMPOSIO_SEARCH_TOOLS'],
4185 config: {
4186 ...mockSessionRetrieveResponse.config,
4187 preload: { tools: 'all' },
4188 },
4189 experimental: {
4190 custom_tools: [
4191 {
4192 slug: 'LOCAL_GREP',
4193 original_slug: 'GREP',
4194 extends_toolkit: null,
4195 },
4196 ],
4197 },
4198 });
4199 mockProvider.wrapTools.mockReturnValue('mocked-custom-tools');
4200 mockClient.toolRouter.session.search.mockResolvedValueOnce({
4201 success: true,
4202 error: null,
4203 results: [],
4204 tool_schemas: {},
4205 toolkit_connection_statuses: [],
4206 next_steps_guidance: [],
4207 session: {
4208 id: sessionId,
4209 generate_id: false,
4210 instructions: 'Reuse session',
4211 },
4212 time_info: {
4213 current_time_utc: '2025-03-09T12:00:00.000Z',
4214 current_time_utc_epoch_seconds: 1741521600,
4215 message: 'UTC',
4216 },
4217 });
4218
4219 const session = await toolRouter.use(sessionId, { customTools: [grepTool] });
4220 await session.tools();
4221 await session.search({ query: 'search local text' });
4222
4223 const wrappedTools = mockProvider.wrapTools.mock.calls[0][0] as Array<{ slug: string }>;
4224 expect(wrappedTools.map(tool => tool.slug)).toEqual(['COMPOSIO_SEARCH_TOOLS', 'LOCAL_GREP']);
4225 expect(mockClient.toolRouter.session.search).toHaveBeenCalledWith(
4226 sessionId,
4227 {
4228 queries: [{ use_case: 'search local text' }],
4229 experimental: {
4230 custom_tools: [expect.objectContaining({ slug: 'GREP', preload: true })],
4231 },
4232 },
4233 undefined
4234 );
4235 });
4236 it('should handle different session IDs', async () => {
4237 const session1Response = {
4238 ...mockSessionRetrieveResponse,
4239 session_id: 'session_1',
4240 };
4241
4242 const session2Response = {
4243 ...mockSessionRetrieveResponse,
4244 session_id: 'session_2',
4245 };
4246
4247 mockClient.toolRouter.session.retrieve
4248 .mockResolvedValueOnce(session1Response)
4249 .mockResolvedValueOnce(session2Response);
4250
4251 const session1 = await toolRouter.use('session_1');
4252 const session2 = await toolRouter.use('session_2');
4253
4254 expect(session1.sessionId).toBe('session_1');
4255 expect(session2.sessionId).toBe('session_2');
4256 expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(2);
4257 expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(
4258 1,
4259 'session_1',
4260 undefined
4261 );
4262 expect(mockClient.toolRouter.session.retrieve).toHaveBeenNthCalledWith(
4263 2,
4264 'session_2',
4265 undefined
4266 );
4267 expect(mockClient.post).not.toHaveBeenCalled();
4268 });
4269
4270 it('should handle MCP server type correctly', async () => {
4271 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4272
4273 const session = await toolRouter.use(sessionId);
4274
4275 expect(session.mcp.type).toBe('http');
4276 expect(session.mcp.url).toBe(
4277 'https://api.composio.dev/api/v3/tool_router/session/session_123'
4278 );
4279 });
4280
4281 it('should throw error if session retrieve fails', async () => {
4282 const error = new Error('Session not found');
4283 mockClient.toolRouter.session.retrieve.mockRejectedValueOnce(error);
4284
4285 await expect(toolRouter.use(sessionId)).rejects.toThrow('Session not found');
4286 expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledWith(sessionId, undefined);
4287 expect(mockClient.post).not.toHaveBeenCalled();
4288 });
4289
4290 it('should handle retrieve with different tool lists', async () => {
4291 const customResponse = {
4292 ...mockSessionRetrieveResponse,
4293 tool_router_tools: ['CUSTOM_TOOL_1', 'CUSTOM_TOOL_2'],
4294 };
4295
4296 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(customResponse);
4297
4298 const session = await toolRouter.use(sessionId);
4299
4300 expect(session).toBeDefined();
4301 expect(session.sessionId).toBe('session_123');
4302 });
4303
4304 it('should be independent from create method', async () => {
4305 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
4306 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4307
4308 // Create a new session
4309 const createdSession = await toolRouter.create('user_123');
4310 expect(createdSession.sessionId).toBe('session_123');
4311
4312 // Use an existing session
4313 const retrievedSession = await toolRouter.use('session_123');
4314 expect(retrievedSession.sessionId).toBe('session_123');
4315
4316 // Both should have been called once
4317 expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
4318 expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(1);
4319 expect(mockClient.post).not.toHaveBeenCalled();
4320 });
4321 });
4322
4323 describe('update method', () => {
4324 const sessionId = 'session_123';
4325 const patchedConfig: ToolRouterSessionConfig = {
4326 ...mockSessionRetrieveResponse.config,
4327 toolkits: { enabled: ['gmail'] },
4328 tags: { enabled: ['readOnlyHint'] },
4329 preload: { tools: ['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL'] },
4330 workbench: { enable: false },
4331 };
4332
4333 beforeEach(() => {
4334 mockClient.toolRouter.session.patch.mockResolvedValue({
4335 session_id: sessionId,
4336 config: patchedConfig,
4337 config_version: 8,
4338 warnings: [{ code: 'TOOLKIT_NOT_CONNECTED', message: 'gmail is not connected' }],
4339 });
4340 });
4341
4342 it('should resolve to the updated session config', async () => {
4343 const session = await toolRouter.use(sessionId);
4344
4345 const config = await session.update({ toolkits: ['gmail'], tags: ['readOnlyHint'] });
4346
4347 expect(mockClient.toolRouter.session.patch).toHaveBeenCalledWith(
4348 sessionId,
4349 expect.objectContaining({ toolkits: { enable: ['gmail'] } }),
4350 { maxRetries: 0 }
4351 );
4352 expect(config).toEqual(patchedConfig);
4353 expect(config.toolkits).toEqual({ enabled: ['gmail'] });
4354 });
4355
4356 it('should refresh config, preload, sandbox, configVersion and warnings in place', async () => {
4357 const session = await toolRouter.use(sessionId);
4358 expect(session.config).toEqual(mockSessionRetrieveResponse.config);
4359 expect(session.configVersion).toBe(7);
4360
4361 const config = await session.update({ toolkits: ['gmail'] });
4362
4363 expect(session.config).toBe(config);
4364 expect(session.preload.tools).toEqual(['GMAIL_FETCH_EMAILS', 'GMAIL_SEND_EMAIL']);
4365 expect(session.sandbox).toEqual({ enable: false });
4366 expect(session.configVersion).toBe(8);
4367 expect(session.warnings).toEqual([
4368 { code: 'TOOLKIT_NOT_CONNECTED', message: 'gmail is not connected' },
4369 ]);
4370 });
4371 });
4372
4373 describe('session.listConfigHistory', () => {
4374 const sessionId = 'session_123';
4375 const rawHistoryItem = {
4376 version: 2,
4377 created_at: '2026-01-02T00:00:00Z',
4378 is_current: true,
4379 config: {
4380 user_id: 'user_123',
4381 toolkits: { enabled: ['github'] },
4382 preload: { tools: [] },
4383 search: {},
4384 execute: {},
4385 },
4386 };
4387
4388 it('should page through the session config history', async () => {
4389 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4390 mockClient.toolRouter.session.configHistory.mockResolvedValueOnce({
4391 items: [rawHistoryItem, { ...rawHistoryItem, version: 1, is_current: false }],
4392 next_cursor: 'cursor_2',
4393 total_pages: 2,
4394 current_page: 1,
4395 total_items: 3,
4396 });
4397
4398 const session = await toolRouter.use(sessionId);
4399 const result = await session.listConfigHistory({ limit: 2 });
4400
4401 expect(mockClient.toolRouter.session.configHistory).toHaveBeenCalledWith(
4402 sessionId,
4403 { cursor: undefined, limit: 2 },
4404 undefined
4405 );
4406 expect(result).toEqual({
4407 items: [
4408 {
4409 version: 2,
4410 createdAt: '2026-01-02T00:00:00Z',
4411 isCurrent: true,
4412 config: rawHistoryItem.config,
4413 },
4414 {
4415 version: 1,
4416 createdAt: '2026-01-02T00:00:00Z',
4417 isCurrent: false,
4418 config: rawHistoryItem.config,
4419 },
4420 ],
4421 nextCursor: 'cursor_2',
4422 totalPages: 2,
4423 currentPage: 1,
4424 totalItems: 3,
4425 });
4426 });
4427
4428 it('should expose each historical Instant policy under instant', async () => {
4429 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4430 mockClient.toolRouter.session.configHistory.mockResolvedValueOnce({
4431 items: [
4432 {
4433 ...rawHistoryItem,
4434 config: {
4435 ...rawHistoryItem.config,
4436 instant: { toolkits: { enabled: ['exa'] }, return_instant_charge: true },
4437 },
4438 },
4439 {
4440 ...rawHistoryItem,
4441 version: 1,
4442 is_current: false,
4443 config: { ...rawHistoryItem.config, instant: false },
4444 },
4445 ],
4446 total_pages: 1,
4447 current_page: 1,
4448 total_items: 2,
4449 });
4450
4451 const session = await toolRouter.use(sessionId);
4452 const { items } = await session.listConfigHistory();
4453
4454 expect(items.map(item => item.config)).toEqual([
4455 {
4456 ...rawHistoryItem.config,
4457 instant: { toolkits: { enabled: ['exa'] }, return_instant_charge: true },
4458 },
4459 { ...rawHistoryItem.config, instant: false },
4460 ]);
4461 });
4462
4463 it('should default nextCursor to null and forward request options', async () => {
4464 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4465 mockClient.toolRouter.session.configHistory.mockResolvedValueOnce({
4466 items: [],
4467 total_pages: 0,
4468 current_page: 1,
4469 total_items: 0,
4470 });
4471 const signal = new AbortController().signal;
4472
4473 const session = await toolRouter.use(sessionId);
4474 const result = await session.listConfigHistory(undefined, { signal });
4475
4476 expect(mockClient.toolRouter.session.configHistory).toHaveBeenCalledWith(
4477 sessionId,
4478 { cursor: undefined, limit: undefined },
4479 { signal }
4480 );
4481 expect(result.nextCursor).toBeNull();
4482 });
4483
4484 it('should throw a ValidationError for invalid options', async () => {
4485 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(mockSessionRetrieveResponse);
4486
4487 const session = await toolRouter.use(sessionId);
4488
4489 await expect(
4490 session.listConfigHistory({ limit: 'ten' as unknown as number })
4491 ).rejects.toThrow(ValidationError);
4492 expect(mockClient.toolRouter.session.configHistory).not.toHaveBeenCalled();
4493 });
4494
4495 describe('update contract', () => {
4496 const patchResponse = (
4497 configVersion: number,
4498 preloadTools: string[] = ['SLACK_SEND_MESSAGE']
4499 ) => ({
4500 session_id: sessionId,
4501 config: {
4502 ...mockSessionRetrieveResponse.config,
4503 preload: { tools: preloadTools },
4504 },
4505 config_version: configVersion,
4506 warnings: [],
4507 });
4508
4509 const patchCall = (callIndex = 0) => {
4510 const call = mockClient.toolRouter.session.patch.mock.calls[callIndex] as [
4511 string,
4512 Record<string, unknown>,
4513 Record<string, unknown> | undefined,
4514 ];
4515 return { body: call[1], options: call[2] };
4516 };
4517
4518 const conflict = () =>
4519 new ConflictError(409, { error: 'version conflict' }, 'Conflict', new Headers());
4520
4521 beforeEach(() => {
4522 mockClient.toolRouter.session.patch.mockResolvedValue(patchResponse(8));
4523 });
4524
4525 it('sends no precondition by default, without retries', async () => {
4526 const session = await toolRouter.use(sessionId);
4527 expect(session.configVersion).toBe(7);
4528
4529 await session.update({ toolkits: ['gmail'] });
4530
4531 const { body, options } = patchCall();
4532 expect(body).not.toHaveProperty('expected_config_version');
4533 expect(body).not.toHaveProperty('expectedConfigVersion');
4534 expect(body.toolkits).toEqual({ enable: ['gmail'] });
4535 expect(options).toEqual({ maxRetries: 0 });
4536 expect(session.configVersion).toBe(8);
4537 expect(session.preload.tools).toEqual(['SLACK_SEND_MESSAGE']);
4538 });
4539
4540 it('forwards the caller request options next to the retry opt-out', async () => {
4541 const session = await toolRouter.use(sessionId);
4542 const signal = new AbortController().signal;
4543
4544 await session.update({ toolkits: ['gmail'] }, { signal });
4545
4546 expect(patchCall().options).toEqual({ signal, maxRetries: 0 });
4547 });
4548
4549 it('sends no precondition when the caller opts out with expectedConfigVersion: false', async () => {
4550 const session = await toolRouter.use(sessionId);
4551
4552 await session.update({ toolkits: ['gmail'], expectedConfigVersion: false });
4553
4554 expect(patchCall().body).not.toHaveProperty('expected_config_version');
4555 });
4556
4557 it('sends an explicit expectedConfigVersion as the precondition', async () => {
4558 const session = await toolRouter.use(sessionId);
4559
4560 await session.update({ toolkits: ['gmail'], expectedConfigVersion: 9 });
4561
4562 expect(patchCall().body.expected_config_version).toBe(9);
4563 });
4564
4565 it('rejects a non-positive expectedConfigVersion before calling the API', async () => {
4566 const session = await toolRouter.use(sessionId);
4567
4568 await expect(session.update({ expectedConfigVersion: 0 })).rejects.toThrow();
4569 expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4570 });
4571
4572 it('sends an explicit null callback URL so the stored callback is removed', async () => {
4573 const session = await toolRouter.use(sessionId);
4574
4575 await session.update({ manageConnections: { callbackUrl: null } });
4576
4577 expect(patchCall().body.manage_connections).toEqual({ callback_url: null });
4578 });
4579
4580 it('sends proxyExecute as given, expands the boolean shorthand, and null removes the block', async () => {
4581 const session = await toolRouter.use(sessionId);
4582
4583 await session.update({ proxyExecute: { enable: true } });
4584 await session.update({ proxyExecute: { enable: false } });
4585 await session.update({ proxyExecute: true });
4586 await session.update({ proxyExecute: false });
4587 await session.update({ proxyExecute: null });
4588 await session.update({ toolkits: ['gmail'] });
4589
4590 expect(patchCall(0).body.proxy_execute).toEqual({ enable: true });
4591 expect(patchCall(1).body.proxy_execute).toEqual({ enable: false });
4592 expect(patchCall(2).body.proxy_execute).toEqual({ enable: true });
4593 expect(patchCall(3).body.proxy_execute).toEqual({ enable: false });
4594 expect(patchCall(4).body.proxy_execute).toBeNull();
4595 expect(patchCall(5).body).not.toHaveProperty('proxy_execute');
4596 });
4597
4598 it('rejects a proxyExecute block without enable', async () => {
4599 const session = await toolRouter.use(sessionId);
4600
4601 await expect(
4602 // @ts-expect-error enable is required
4603 session.update({ proxyExecute: {} })
4604 ).rejects.toThrow();
4605 expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4606 });
4607
4608 it('preserves an empty toolkit allowlist instead of omitting it', async () => {
4609 const session = await toolRouter.use(sessionId);
4610
4611 await session.update({ toolkits: [] });
4612 await session.update({ toolkits: { enable: [] } });
4613
4614 expect(patchCall(0).body.toolkits).toEqual({ enable: [] });
4615 expect(patchCall(1).body.toolkits).toEqual({ enable: [] });
4616 });
4617
4618 it('sends null for policy blocks the caller clears', async () => {
4619 const session = await toolRouter.use(sessionId);
4620
4621 await session.update({
4622 toolkits: null,
4623 tools: null,
4624 tags: null,
4625 authConfigs: null,
4626 connectedAccounts: null,
4627 preload: null,
4628 multiAccount: null,
4629 search: null,
4630 execute: null,
4631 experimental: null,
4632 });
4633
4634 expect(patchCall().body).toEqual({
4635 toolkits: null,
4636 tools: null,
4637 tags: null,
4638 auth_configs: null,
4639 connected_accounts: null,
4640 preload: null,
4641 multi_account: null,
4642 search: null,
4643 execute: null,
4644 experimental: null,
4645 });
4646 });
4647
4648 it('surfaces a 409 as a typed conflict error and leaves local state untouched', async () => {
4649 const session = await toolRouter.use(sessionId);
4650 const preloadBefore = session.preload;
4651 mockClient.toolRouter.session.patch.mockRejectedValueOnce(conflict());
4652
4653 const failure = await session
4654 .update({ toolkits: ['gmail'], expectedConfigVersion: session.configVersion })
4655 .catch(e => e);
4656
4657 expect(failure).toBeInstanceOf(ComposioSessionConfigConflictError);
4658 expect(failure.message).toMatch(/re-fetch/i);
4659 expect(failure.message).toMatch(/retry/i);
4660 expect(failure.statusCode).toBe(409);
4661 expect(failure.meta).toMatchObject({ sessionId, expectedConfigVersion: 7 });
4662 expect(session.configVersion).toBe(7);
4663 expect(session.preload).toBe(preloadBefore);
4664 expect(session.preload.tools).toEqual(['GMAIL_FETCH_EMAILS']);
4665 });
4666
4667 it.each([
4668 ['by default', {}],
4669 ['with expectedConfigVersion: false', { expectedConfigVersion: false as const }],
4670 ])(
4671 'reports an in-flight change when a 409 arrives without a precondition (%s)',
4672 async (_label, optOut) => {
4673 const session = await toolRouter.use(sessionId);
4674 const configBefore = session.config;
4675 mockClient.toolRouter.session.patch.mockRejectedValueOnce(conflict());
4676
4677 const failure = await session.update({ toolkits: ['gmail'], ...optOut }).catch(e => e);
4678
4679 expect(failure).toBeInstanceOf(ComposioSessionConfigConflictError);
4680 expect(failure.message).toMatch(/changed while this update was in flight/);
4681 expect(failure.message).not.toMatch(/no longer at version/);
4682 expect(failure.meta?.expectedConfigVersion).toBeUndefined();
4683 expect(session.config).toBe(configBefore);
4684 expect(session.configVersion).toBe(7);
4685 }
4686 );
4687
4688 it('lets the first of two handles at version N win and the stale one conflict until re-read', async () => {
4689 const first = await toolRouter.use(sessionId);
4690 const second = await toolRouter.use(sessionId);
4691 expect(first.configVersion).toBe(7);
4692 expect(second.configVersion).toBe(7);
4693
4694 await first.update({ toolkits: ['gmail'], expectedConfigVersion: first.configVersion });
4695 expect(patchCall(0).body.expected_config_version).toBe(7);
4696 expect(first.configVersion).toBe(8);
4697
4698 mockClient.toolRouter.session.patch.mockRejectedValueOnce(conflict());
4699 await expect(
4700 second.update({ toolkits: ['slack'], expectedConfigVersion: second.configVersion })
4701 ).rejects.toBeInstanceOf(ComposioSessionConfigConflictError);
4702 expect(patchCall(1).body.expected_config_version).toBe(7);
4703 expect(second.configVersion).toBe(7);
4704 expect(second.preload.tools).toEqual(['GMAIL_FETCH_EMAILS']);
4705
4706 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce({
4707 ...mockSessionRetrieveResponse,
4708 config_version: 8,
4709 });
4710 const reread = await toolRouter.use(sessionId);
4711 expect(reread.configVersion).toBe(8);
4712 mockClient.toolRouter.session.patch.mockResolvedValueOnce(patchResponse(9));
4713 await reread.update({ toolkits: ['slack'], expectedConfigVersion: reread.configVersion });
4714 expect(patchCall(2).body.expected_config_version).toBe(8);
4715 expect(reread.configVersion).toBe(9);
4716 });
4717 });
4718 });
4719
4720 describe('saved Session configs on an existing session', () => {
4721 const sessionId = 'session_123';
4722
4723 const patchResponse = (configVersion: number, experimental?: Record<string, unknown>) => ({
4724 session_id: sessionId,
4725 config: mockSessionRetrieveResponse.config,
4726 config_version: configVersion,
4727 warnings: [],
4728 ...(experimental && { experimental }),
4729 });
4730
4731 const patchBody = (callIndex = 0) =>
4732 mockClient.toolRouter.session.patch.mock.calls[callIndex][1] as Record<string, unknown>;
4733
4734 // Plain JavaScript callers bypass the compile-time union.
4735 type UpdateInput = Parameters<Session<unknown, unknown, MockProvider>['update']>[0];
4736 const unchecked = (config: Record<string, unknown>) => config as unknown as UpdateInput;
4737
4738 beforeEach(() => {
4739 mockClient.toolRouter.session.patch.mockResolvedValue(patchResponse(8));
4740 });
4741
4742 describe('mixed-input rejection', () => {
4743 it.each([
4744 ['toolkits', { toolkits: ['gmail'] }],
4745 ['toolkits', { toolkits: null }],
4746 ['tools', { tools: { gmail: ['GMAIL_SEND_EMAIL'] } }],
4747 ['tools', { tools: null }],
4748 ['tags', { tags: ['readOnlyHint'] }],
4749 ['tags', { tags: null }],
4750 ])('rejects sessionConfigId combined with %s (%j) without a PATCH', async (field, inline) => {
4751 const session = await toolRouter.use(sessionId);
4752
4753 const error = await session
4754 .update(unchecked({ ...inline, experimental: { sessionConfigId: 'sc_1' } }))
4755 .catch(e => e);
4756
4757 expect(error).toBeInstanceOf(ValidationError);
4758 expect(error.message).toContain(
4759 `experimental.sessionConfigId cannot be combined with ${field}`
4760 );
4761 expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4762 });
4763
4764 it('sends sessionConfigId next to per-session fields', async () => {
4765 const session = await toolRouter.use(sessionId);
4766
4767 await session.update({
4768 authConfigs: { github: 'ac_1' },
4769 preload: null,
4770 experimental: { sessionConfigId: 'sc_1' },
4771 });
4772
4773 expect(patchBody()).toEqual({
4774 auth_configs: { github: 'ac_1' },
4775 preload: null,
4776 experimental: { session_config_id: 'sc_1' },
4777 });
4778 });
4779
4780 it('allows sessionConfigId with other experimental settings', async () => {
4781 const session = await toolRouter.use(sessionId);
4782
4783 await session.update({ experimental: { sessionConfigId: 'sc_1', fastMode: true } });
4784
4785 expect(patchBody().experimental).toEqual({ session_config_id: 'sc_1', fast_mode: true });
4786 });
4787
4788 it('treats an explicit undefined toolkits as absent', async () => {
4789 const session = await toolRouter.use(sessionId);
4790
4791 await session.update({ toolkits: undefined, experimental: { sessionConfigId: 'sc_1' } });
4792
4793 expect(patchBody()).not.toHaveProperty('toolkits');
4794 expect(patchBody().experimental).toEqual({ session_config_id: 'sc_1' });
4795 });
4796
4797 it('rejects an empty sessionConfigId before any PATCH', async () => {
4798 const session = await toolRouter.use(sessionId);
4799
4800 await expect(session.update({ experimental: { sessionConfigId: '' } })).rejects.toThrow();
4801 expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4802 });
4803
4804 it('keeps throwing ZodError for unrelated invalid input', async () => {
4805 const session = await toolRouter.use(sessionId);
4806
4807 const error = await session.update({ expectedConfigVersion: 0 }).catch(e => e);
4808
4809 expect(error).toBeInstanceOf(z.ZodError);
4810 expect(error).not.toBeInstanceOf(ValidationError);
4811 expect(mockClient.toolRouter.session.patch).not.toHaveBeenCalled();
4812 });
4813 });
4814
4815 describe('sourceSessionConfig', () => {
4816 const withSource = <T extends object>(response: T, id: string) => ({
4817 ...response,
4818 experimental: { source_session_config: { id } },
4819 });
4820
4821 it('is set from the create response', async () => {
4822 mockClient.toolRouter.session.create.mockResolvedValueOnce(
4823 withSource(mockSessionCreateResponse, 'sc_1')
4824 );
4825
4826 const session = await toolRouter.create('user_123', {
4827 experimental: { sessionConfigId: 'sc_1' },
4828 });
4829
4830 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_1' });
4831 });
4832
4833 it('is undefined when the create response has no experimental block', async () => {
4834 mockClient.toolRouter.session.create.mockResolvedValueOnce(mockSessionCreateResponse);
4835
4836 const session = await toolRouter.create('user_123');
4837
4838 expect(session.experimental.sourceSessionConfig).toBeUndefined();
4839 });
4840
4841 it('is set from the retrieve response on use()', async () => {
4842 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(
4843 withSource(mockSessionRetrieveResponse, 'sc_1')
4844 );
4845
4846 const session = await toolRouter.use(sessionId);
4847
4848 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_1' });
4849 });
4850
4851 it('is set from the attach response on use() with custom tools', async () => {
4852 const customTool = createCustomTool('MY_TOOL', {
4853 name: 'My tool',
4854 description: 'Does a thing',
4855 inputParams: z.object({}),
4856 execute: async () => ({ ok: true }),
4857 });
4858 mockClient.toolRouter.session.attach.mockResolvedValueOnce(
4859 withSource(mockSessionRetrieveResponse, 'sc_1')
4860 );
4861
4862 const session = await toolRouter.use(sessionId, { customTools: [customTool] });
4863
4864 expect(mockClient.toolRouter.session.attach).toHaveBeenCalled();
4865 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_1' });
4866 });
4867
4868 it('copies only the id', async () => {
4869 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce({
4870 ...mockSessionRetrieveResponse,
4871 experimental: { source_session_config: { id: 'sc_1', name: 'Daily digest' } },
4872 });
4873
4874 const session = await toolRouter.use(sessionId);
4875
4876 expect(session.experimental.sourceSessionConfig).toStrictEqual({ id: 'sc_1' });
4877 });
4878
4879 it('is replaced by the config the update response reports', async () => {
4880 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(
4881 withSource(mockSessionRetrieveResponse, 'sc_1')
4882 );
4883 mockClient.toolRouter.session.patch.mockResolvedValueOnce(
4884 withSource(patchResponse(8), 'sc_2')
4885 );
4886 const session = await toolRouter.use(sessionId);
4887
4888 await session.update({ experimental: { sessionConfigId: 'sc_2' } });
4889
4890 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_2' });
4891 });
4892
4893 it('survives an inline update whose response still carries it, then clears when omitted', async () => {
4894 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(
4895 withSource(mockSessionRetrieveResponse, 'sc_1')
4896 );
4897 mockClient.toolRouter.session.patch
4898 .mockResolvedValueOnce(withSource(patchResponse(8), 'sc_1'))
4899 .mockResolvedValueOnce(patchResponse(9));
4900 const session = await toolRouter.use(sessionId);
4901
4902 await session.update({ toolkits: ['gmail'] });
4903 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_1' });
4904
4905 await session.update({ toolkits: ['slack'] });
4906 expect(session.experimental.sourceSessionConfig).toBeUndefined();
4907 });
4908
4909 it('makes no extra lookups from tools(), search() or execute()', async () => {
4910 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce(
4911 withSource(mockSessionRetrieveResponse, 'sc_1')
4912 );
4913 mockClient.toolRouter.session.search.mockResolvedValueOnce({
4914 success: true,
4915 error: null,
4916 results: [],
4917 tool_schemas: {},
4918 toolkit_connection_statuses: [],
4919 next_steps_guidance: [],
4920 session: { id: sessionId, generate_id: false, instructions: '' },
4921 time_info: {
4922 current_time_utc: '2026-01-01T00:00:00Z',
4923 current_time_utc_epoch_seconds: 0,
4924 message: '',
4925 },
4926 });
4927 mockClient.toolRouter.session.execute.mockResolvedValueOnce({
4928 result_type: 'completed',
4929 data: {},
4930 error: null,
4931 log_id: 'log_1',
4932 });
4933 const session = await toolRouter.use(sessionId);
4934
4935 await session.tools();
4936 await session.search({ query: 'send an email' });
4937 await session.execute('GMAIL_SEND_EMAIL', {});
4938
4939 // The mock client has no `sessionConfigs`, so any lookup would throw.
4940 expect(mockClient.toolRouter.session.retrieve).toHaveBeenCalledTimes(1);
4941 });
4942 });
4943
4944 describe('fail closed', () => {
4945 it.each([
4946 [new BadRequestError(400, undefined, 'Bad request', {}), {}],
4947 [new PermissionDeniedError(403, undefined, 'Forbidden', {}), {}],
4948 [new NotFoundError(404, undefined, 'Not found', {}), {}],
4949 [new ConflictError(409, undefined, 'Conflict', {}), {}],
4950 [new ConflictError(409, undefined, 'Conflict', {}), { expectedConfigVersion: 7 }],
4951 ])('preserves state and does not retry after %s with %j', async (error, precondition) => {
4952 mockClient.toolRouter.session.retrieve.mockResolvedValueOnce({
4953 ...mockSessionRetrieveResponse,
4954 experimental: { source_session_config: { id: 'sc_1' } },
4955 });
4956 mockClient.toolRouter.session.patch.mockRejectedValueOnce(error);
4957 const session = await toolRouter.use(sessionId);
4958 const configBefore = session.config;
4959
4960 const failure = await session
4961 .update({ experimental: { sessionConfigId: 'sc_2' }, ...precondition })
4962 .catch(e => e);
4963
4964 if (error.status === 409) {
4965 expect(failure).toBeInstanceOf(ComposioSessionConfigConflictError);
4966 expect(failure.statusCode).toBe(409);
4967 expect(failure.message).toContain(sessionId);
4968 expect(failure.message).toContain('sc_2');
4969 expect(failure.message).toMatch(/re-fetch/i);
4970 expect(failure.message).toMatch(/retry/i);
4971 expect(failure.message).not.toMatch(/no longer at version/);
4972 expect(failure.meta).toMatchObject({ sessionId, sessionConfigId: 'sc_2' });
4973 } else {
4974 expect(failure).toBe(error);
4975 }
4976 expect(mockClient.toolRouter.session.patch).toHaveBeenCalledTimes(1);
4977 expect(session.config).toBe(configBefore);
4978 expect(session.configVersion).toBe(7);
4979 expect(session.experimental.sourceSessionConfig).toEqual({ id: 'sc_1' });
4980 });
4981
4982 it.each([
4983 ['403', () => new PermissionDeniedError(403, undefined, 'Forbidden', {})],
4984 ['404', () => new NotFoundError(404, undefined, 'Not found', {})],
4985 ])(
4986 'surfaces a %s from create unchanged and never retries without the config',
4987 async (_status, makeError) => {
4988 const error = makeError();
4989 mockClient.toolRouter.session.create.mockRejectedValueOnce(error);
4990
4991 await expect(
4992 toolRouter.create('user_123', { experimental: { sessionConfigId: 'sc_archived' } })
4993 ).rejects.toBe(error);
4994
4995 expect(mockClient.toolRouter.session.create).toHaveBeenCalledTimes(1);
4996 expect(mockClient.toolRouter.session.create.mock.calls[0][0].experimental).toEqual({
4997 session_config_id: 'sc_archived',
4998 });
4999 }
5000 );
Showing first 5,000 of 5,003 lines. View raw