Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | }); |