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 523 lines 17.6 KB
Raw
1 import { describe, it, expect, vi, assert } from 'vitest';
2 import ComposioClient, { Auth, createFetchTransport } from '@composio/client';
3 import { z } from 'zod/v3';
4 import { Tools } from '../../src/models/Tools';
5 import { ToolRouterSession } from '../../src/models/ToolRouterSession';
6 import { SessionContextImpl } from '../../src/models/SessionContext';
7 import { inspect, format } from 'node:util';
8 import { ComposioError, ComposioToolInputRequiredError, ValidationError } from '../../src/errors';
9 import logger from '../../src/utils/logger';
10 import { buildCustomToolsMap, createCustomTool } from '../../src/models/CustomTool';
11 import type { CustomToolsMap, SessionContext } from '../../src/types/customTool.types';
12 import { MockProvider } from '../utils/mocks/provider.mock';
13
14 vi.mock('../../src/telemetry/Telemetry', () => ({
15 telemetry: { instrument: vi.fn() },
16 }));
17
18 // The execute and proxy-execute endpoints answer `result_type: "input_required"`
19 // when a call needs the user's input (an approval, for example) before it can
20 // run. That answer carries no data, log ID or HTTP status, so it cannot be
21 // returned as an execution result: every execution path raises it as a typed
22 // error that carries the questions and the opaque `request_state`.
23 //
24 // These tests run a real client against a stubbed `fetch` so they cover the
25 // wire shape the generated client hands to the SDK.
26
27 const SESSION_ID = 'sess_123';
28
29 const inputRequired = {
30 result_type: 'input_required',
31 input_requests: {
32 approval_1: {
33 type: 'elicitation',
34 mode: 'form',
35 message: 'Allow GMAIL_SEND_EMAIL to send this email?',
36 requested_schema: {
37 type: 'object',
38 properties: { approved: { type: 'boolean' } },
39 required: ['approved'],
40 },
41 },
42 },
43 request_state: 'opaque-state-token',
44 };
45
46 const createClient = (body: unknown) => {
47 const fetch = vi.fn<typeof globalThis.fetch>(
48 async () =>
49 new Response(JSON.stringify(body), {
50 status: 200,
51 headers: { 'content-type': 'application/json' },
52 })
53 );
54 const client = new ComposioClient({
55 auth: Auth.project('test-api-key'),
56 baseURL: 'https://backend.invalid',
57 transport: createFetchTransport({ fetch }),
58 });
59 return { client, fetch };
60 };
61
62 const createSession = (client: ComposioClient) =>
63 new ToolRouterSession(client, { apiKey: 'key', provider: new MockProvider() }, SESSION_ID, {
64 type: 'http' as const,
65 url: `https://backend.invalid/api/v3/tool_router/session/${SESSION_ID}`,
66 });
67
68 const proxyParams = {
69 toolkit: 'github',
70 endpoint: 'https://api.github.com/user/repos?token=secret',
71 method: 'POST' as const,
72 body: { name: 'repo' },
73 };
74
75 const executionPaths: Array<{
76 name: string;
77 subject: string;
78 run: (client: ComposioClient) => Promise<unknown>;
79 }> = [
80 {
81 name: 'provider-wrapped session tool',
82 subject: 'Tool GMAIL_SEND_EMAIL',
83 run: client =>
84 new Tools(client, { provider: new MockProvider() }).executeSessionTool('GMAIL_SEND_EMAIL', {
85 sessionId: SESSION_ID,
86 arguments: { to: 'test@test.com' },
87 }),
88 },
89 {
90 name: 'session.execute',
91 subject: 'Tool GMAIL_SEND_EMAIL',
92 run: client => createSession(client).execute('GMAIL_SEND_EMAIL', { to: 'test@test.com' }),
93 },
94 {
95 name: 'session.executeMeta',
96 subject: 'Tool COMPOSIO_MULTI_EXECUTE_TOOL',
97 run: client =>
98 createSession(client).executeMeta('COMPOSIO_MULTI_EXECUTE_TOOL', {
99 tools: [{ tool_slug: 'GMAIL_SEND_EMAIL', arguments: { to: 'test@test.com' } }],
100 }),
101 },
102 {
103 name: 'session.proxyExecute',
104 subject: 'POST proxy call for toolkit github',
105 run: client => createSession(client).proxyExecute(proxyParams),
106 },
107 {
108 name: 'custom tool context execute',
109 subject: 'Tool GMAIL_SEND_EMAIL',
110 run: client =>
111 new SessionContextImpl(client, 'test-user', SESSION_ID).execute('GMAIL_SEND_EMAIL', {
112 to: 'test@test.com',
113 }),
114 },
115 {
116 name: 'custom tool context proxyExecute',
117 subject: 'POST proxy call for toolkit github',
118 run: client =>
119 new SessionContextImpl(client, 'test-user', SESSION_ID).proxyExecute(proxyParams),
120 },
121 ];
122
123 describe('execution that requires user input', () => {
124 it.each(executionPaths)(
125 '$name raises ComposioToolInputRequiredError',
126 async ({ run, subject }) => {
127 const { client, fetch } = createClient(inputRequired);
128
129 const error = await run(client).catch((caught: unknown) => caught);
130
131 assert(error instanceof ComposioToolInputRequiredError);
132 expect(error.code).toBe('TS-SDK::TOOL_INPUT_REQUIRED');
133 expect(error.message).toContain(`${subject} requires user input`);
134 expect(error.message).toContain('inputResponses');
135 // The opaque state and the proxied URL stay out of the message.
136 expect(error.message).not.toContain('opaque-state-token');
137 expect(error.message).not.toContain('secret');
138 expect(error.requestState).toBe('opaque-state-token');
139 expect(error.inputRequests).toEqual({
140 approval_1: {
141 type: 'elicitation',
142 mode: 'form',
143 message: 'Allow GMAIL_SEND_EMAIL to send this email?',
144 requestedSchema: {
145 type: 'object',
146 properties: { approved: { type: 'boolean' } },
147 required: ['approved'],
148 },
149 },
150 });
151 // The call is not repeated: answering needs the user.
152 expect(fetch).toHaveBeenCalledTimes(1);
153 }
154 );
155
156 // `request_state` is continuation state. It stays readable for the code that
157 // answers the request and out of everything an error is routinely dumped into.
158 it('keeps requestState out of inspection, serialization and pretty printing', async () => {
159 const { client } = createClient(inputRequired);
160 const logged = vi.spyOn(logger, 'error').mockImplementation(() => {});
161
162 const error = await createSession(client)
163 .execute('GMAIL_SEND_EMAIL', {})
164 .catch((caught: unknown) => caught);
165
166 assert(error instanceof ComposioToolInputRequiredError);
167 expect(error.requestState).toBe('opaque-state-token');
168
169 const inspected = inspect(error, { depth: null });
170 expect(inspected).toContain('ComposioToolInputRequiredError');
171 expect(inspected).toContain('approval_1');
172 expect(inspected).not.toContain('opaque-state-token');
173 // The message names the property; the property itself is not printed.
174 expect(inspected).not.toMatch(/requestState:/);
175 // What `console.error(error)` writes.
176 expect(format(error)).not.toContain('opaque-state-token');
177
178 const serialized = JSON.stringify(error);
179 expect(serialized).toContain('approval_1');
180 expect(serialized).not.toContain('opaque-state-token');
181 expect(JSON.parse(serialized)).not.toHaveProperty('requestState');
182
183 expect(Object.keys(error)).not.toContain('requestState');
184 expect({ ...error }).not.toHaveProperty('requestState');
185
186 error.prettyPrint(true);
187 ComposioError.handle(error, { includeStack: true });
188 expect(logged).toHaveBeenCalled();
189 expect(JSON.stringify(logged.mock.calls)).not.toContain('opaque-state-token');
190 logged.mockRestore();
191 });
192
193 it('leaves requestState undefined when the API returns none', async () => {
194 const { client } = createClient({ ...inputRequired, request_state: undefined });
195
196 const error = await createSession(client)
197 .execute('GMAIL_SEND_EMAIL', {})
198 .catch((caught: unknown) => caught);
199
200 assert(error instanceof ComposioToolInputRequiredError);
201 expect(error.requestState).toBeUndefined();
202 });
203
204 it.each([
205 { name: 'completed', result_type: 'completed' as const, error: null },
206 { name: 'failed', result_type: 'failed' as const, error: 'Connection not found' },
207 ])('session.execute still returns a $name result', async ({ result_type, error }) => {
208 const { client } = createClient({ result_type, data: { id: 'msg_1' }, error, log_id: 'log_1' });
209
210 await expect(createSession(client).execute('GMAIL_SEND_EMAIL', {})).resolves.toEqual({
211 data: { id: 'msg_1' },
212 error,
213 logId: 'log_1',
214 resultType: result_type,
215 });
216 });
217
218 it('session.proxyExecute still returns a completed result', async () => {
219 const { client } = createClient({
220 result_type: 'completed',
221 status: 201,
222 data: { id: 1 },
223 headers: { 'x-request-id': 'req_1' },
224 });
225
226 await expect(createSession(client).proxyExecute(proxyParams)).resolves.toEqual({
227 resultType: 'completed',
228 status: 201,
229 data: { id: 1 },
230 headers: { 'x-request-id': 'req_1' },
231 });
232 });
233 });
234
235 // The answers to an `input_required` call travel on the repeated call as
236 // `input_responses`, with the `request_state` it returned.
237 const answers = {
238 approval_1: { action: 'accept' as const, content: { decision: 'approve' } },
239 };
240
241 const answeringPaths: Array<{
242 name: string;
243 run: (session: ToolRouterSession) => Promise<unknown>;
244 }> = [
245 {
246 name: 'session.execute',
247 run: session =>
248 session.execute(
249 'GMAIL_SEND_EMAIL',
250 { to: 'test@test.com' },
251 { inputResponses: answers, requestState: 'opaque-state-token' }
252 ),
253 },
254 {
255 name: 'session.executeMeta',
256 run: session =>
257 session.executeMeta(
258 'COMPOSIO_MULTI_EXECUTE_TOOL',
259 { tools: [] },
260 { inputResponses: answers, requestState: 'opaque-state-token' }
261 ),
262 },
263 ];
264
265 const sentBody = (fetch: ReturnType<typeof createClient>['fetch']): Record<string, unknown> => {
266 const init = fetch.mock.calls[0]?.[1];
267 assert(typeof init?.body === 'string');
268 return z.record(z.unknown()).parse(JSON.parse(init.body));
269 };
270
271 describe('answering a call that required user input', () => {
272 it.each(answeringPaths)('$name sends the answers and the request state', async ({ run }) => {
273 const { client, fetch } = createClient({
274 result_type: 'completed',
275 data: { id: 'msg_1' },
276 error: null,
277 log_id: 'log_1',
278 });
279
280 await run(createSession(client));
281
282 expect(sentBody(fetch)).toMatchObject({
283 input_responses: answers,
284 request_state: 'opaque-state-token',
285 });
286 });
287
288 it('session.execute sends neither field without answers', async () => {
289 const { client, fetch } = createClient({
290 result_type: 'completed',
291 data: {},
292 error: null,
293 log_id: 'log_1',
294 });
295
296 await createSession(client).execute('GMAIL_SEND_EMAIL', {});
297
298 expect(sentBody(fetch)).not.toHaveProperty('input_responses');
299 expect(sentBody(fetch)).not.toHaveProperty('request_state');
300 });
301 });
302
303 // A local custom tool reaches the API through the `ctx.execute()` and
304 // `ctx.proxyExecute()` helpers. The wrapper that runs the tool turns whatever
305 // it throws into a failed result, which must not happen to an input request:
306 // the caller needs the questions and the request state, not a message.
307 const customToolCalling = (call: (ctx: SessionContext) => Promise<unknown>) =>
308 buildCustomToolsMap([
309 createCustomTool('SEND_WELCOME_EMAIL', {
310 name: 'Send welcome email',
311 description: 'Sends the welcome email through a session helper',
312 inputParams: z.object({}),
313 execute: async (_input, ctx) => ({ sent: await call(ctx) }),
314 }),
315 ]);
316
317 const enclosingToolBodies: Array<{
318 name: string;
319 subject: string;
320 call: (ctx: SessionContext) => Promise<unknown>;
321 }> = [
322 {
323 name: 'ctx.execute()',
324 subject: 'Tool GMAIL_SEND_EMAIL',
325 call: ctx => ctx.execute('GMAIL_SEND_EMAIL', { to: 'test@test.com' }),
326 },
327 {
328 name: 'ctx.proxyExecute()',
329 subject: 'POST proxy call for toolkit github',
330 call: ctx => ctx.proxyExecute(proxyParams),
331 },
332 ];
333
334 const createSessionWithCustomTools = (client: ComposioClient, customToolsMap: CustomToolsMap) =>
335 new ToolRouterSession(
336 client,
337 { apiKey: 'key', provider: new MockProvider() },
338 SESSION_ID,
339 {
340 type: 'http' as const,
341 url: `https://backend.invalid/api/v3/tool_router/session/${SESSION_ID}`,
342 },
343 undefined,
344 customToolsMap,
345 'test-user'
346 );
347
348 describe('custom tool whose body requires user input', () => {
349 it.each(enclosingToolBodies)(
350 'session.execute of a custom tool calling $name raises ComposioToolInputRequiredError',
351 async ({ call, subject }) => {
352 const { client, fetch } = createClient(inputRequired);
353 const session = createSessionWithCustomTools(client, customToolCalling(call));
354
355 const error = await session
356 .execute('SEND_WELCOME_EMAIL', {})
357 .catch((caught: unknown) => caught);
358
359 assert(error instanceof ComposioToolInputRequiredError);
360 expect(error.message).toContain(`${subject} requires user input`);
361 expect(error.requestState).toBe('opaque-state-token');
362 expect(Object.keys(error.inputRequests)).toEqual(['approval_1']);
363 expect(fetch).toHaveBeenCalledTimes(1);
364 }
365 );
366
367 it.each(enclosingToolBodies)(
368 'a sibling custom tool calling $name raises through ctx.execute()',
369 async ({ call }) => {
370 const { client } = createClient(inputRequired);
371 const context = new SessionContextImpl(
372 client,
373 'test-user',
374 SESSION_ID,
375 customToolCalling(call)
376 );
377
378 const error = await context
379 .execute('SEND_WELCOME_EMAIL', {})
380 .catch((caught: unknown) => caught);
381
382 assert(error instanceof ComposioToolInputRequiredError);
383 expect(error.requestState).toBe('opaque-state-token');
384 }
385 );
386
387 it('still turns any other error thrown by the tool into a failed result', async () => {
388 const { client } = createClient(inputRequired);
389 const session = createSessionWithCustomTools(
390 client,
391 customToolCalling(async () => {
392 throw new Error('boom');
393 })
394 );
395
396 await expect(session.execute('SEND_WELCOME_EMAIL', {})).resolves.toEqual({
397 data: {},
398 error: 'boom',
399 logId: '',
400 resultType: 'failed',
401 });
402 });
403 });
404
405 // `result_type` says whether a tool that ran succeeded. A failed execution can
406 // carry a `null` or empty `error`, so success is read from `result_type` alone.
407 const executedAnswers: Array<{
408 name: string;
409 result_type: 'completed' | 'failed';
410 error: string | null;
411 successful: boolean;
412 }> = [
413 { name: 'failed with a null error', result_type: 'failed', error: null, successful: false },
414 { name: 'failed with an empty error', result_type: 'failed', error: '', successful: false },
415 { name: 'failed with a message', result_type: 'failed', error: 'Boom', successful: false },
416 { name: 'completed', result_type: 'completed', error: null, successful: true },
417 ];
418
419 const wireBody = ({ result_type, error }: (typeof executedAnswers)[number]) => ({
420 result_type,
421 data: {},
422 error,
423 log_id: 'log',
424 });
425
426 class TargetProvider extends MockProvider {
427 executeFor(session: ToolRouterSession) {
428 return this.executeToolForTarget(session, 'GMAIL_SEND_EMAIL', {});
429 }
430 }
431
432 describe('session execution success', () => {
433 it.each(executedAnswers)(
434 'provider-wrapped session tool: $name is successful=$successful',
435 async answer => {
436 const { client } = createClient(wireBody(answer));
437
438 const result = await new Tools(client, { provider: new MockProvider() }).executeSessionTool(
439 'GMAIL_SEND_EMAIL',
440 { sessionId: SESSION_ID, arguments: {} }
441 );
442
443 expect(result).toEqual({
444 data: {},
445 // The error is passed through as the API sent it.
446 error: answer.error,
447 successful: answer.successful,
448 logId: 'log',
449 });
450 }
451 );
452
453 it.each(executedAnswers)(
454 'provider tool call bound to a session: $name is successful=$successful',
455 async answer => {
456 const { client } = createClient(wireBody(answer));
457
458 const result = await new TargetProvider().executeFor(createSession(client));
459
460 expect(result.successful).toBe(answer.successful);
461 expect(result.error).toBe(answer.error);
462 }
463 );
464
465 it.each(executedAnswers)('session.execute: $name exposes resultType', async answer => {
466 const { client } = createClient(wireBody(answer));
467
468 const result = await createSession(client).execute('GMAIL_SEND_EMAIL', {});
469
470 expect(result.resultType).toBe(answer.result_type);
471 expect(result.error).toBe(answer.error);
472 });
473
474 it.each(executedAnswers)(
475 'custom tool context execute: $name exposes resultType',
476 async answer => {
477 const { client } = createClient(wireBody(answer));
478
479 const result = await new SessionContextImpl(client, 'test-user', SESSION_ID).execute(
480 'GMAIL_SEND_EMAIL',
481 {}
482 );
483
484 expect(result.resultType).toBe(answer.result_type);
485 expect(result.error).toBe(answer.error);
486 }
487 );
488 });
489
490 // Every session execute answer carries a `result_type`. One without it, or with
491 // a value this SDK does not know, is not a result: reading it as a success or
492 // as a failure would be a guess, so each path raises instead.
493 const invalidAnswers = [
494 { name: 'no result_type', body: { data: {}, error: null, log_id: 'log' } },
495 {
496 name: 'an unknown result_type',
497 body: { result_type: 'deferred', data: {}, error: null, log_id: 'log' },
498 },
499 ];
500
501 const executePaths = executionPaths.filter(path => !path.name.includes('proxyExecute'));
502
503 describe.each(invalidAnswers)('session execute answer with $name', ({ body }) => {
504 it.each(executePaths)('$name raises ValidationError', async ({ run, subject }) => {
505 const { client, fetch } = createClient(body);
506
507 const error = await run(client).catch((caught: unknown) => caught);
508
509 assert(error instanceof ValidationError);
510 expect(error.message).toContain(
511 `${subject} returned an execute response without a known result_type`
512 );
513 expect(fetch).toHaveBeenCalledTimes(1);
514 });
515
516 it('provider tool call bound to a session raises ValidationError', async () => {
517 const { client } = createClient(body);
518
519 await expect(new TargetProvider().executeFor(createSession(client))).rejects.toBeInstanceOf(
520 ValidationError
521 );
522 });
523 });