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 576 lines 20.3 KB
Raw
1 import { normalizeToolArguments } from '@composio/core';
2 import { defineTool } from '@earendil-works/pi-coding-agent';
3 import { Type } from 'typebox';
4
5 import { applyAuthLinkHandlers } from './auth-links';
6 import {
7 defaultIsToolkitConnected,
8 formatDefaultConnectionResult,
9 normalizeToolkitStateMap,
10 toCapabilities,
11 } from './connections';
12 import { runHook } from './hooks';
13 import { defaultFormatResult, hookControls, toPiErrorResult, toPiResult } from './results';
14 import { optionalRecordSchema, ToolkitsSchema } from './schemas';
15 import { DEFAULT_SESSION_TOOL_NAMES } from './types';
16 import type {
17 PiBaseToolContext,
18 PiComposioSessionLike,
19 PiConnectionManagementContext,
20 PiConnectionToolkitResult,
21 PiExecuteContext,
22 PiExecuteHookContext,
23 PiManageConnectionsHookContext,
24 PiProviderOptions,
25 PiRemoteBashHookContext,
26 PiRemoteBashRequest,
27 PiRemoteWorkbenchHookContext,
28 PiRemoteWorkbenchRequest,
29 PiSearchContext,
30 PiSearchHookContext,
31 PiSessionToolCapabilities,
32 PiSessionToolName,
33 PiSessionToolOptions,
34 PiToolCollection,
35 PiToolDetails,
36 } from './types';
37 import { maybeTransform, normalizeToolkits, toolkitFromToolSlug } from './utils';
38
39 export const createPiSessionTools = (
40 input: PiComposioSessionLike | PiSessionToolCapabilities,
41 providerOptions: PiProviderOptions,
42 options: PiSessionToolOptions = {}
43 ): PiToolCollection => {
44 const capabilities = toCapabilities(input, providerOptions, options);
45 const formatter = capabilities.formatResult ?? defaultFormatResult;
46 const catchErrors = capabilities.catchErrors ?? true;
47 const names = { ...DEFAULT_SESSION_TOOL_NAMES, ...(capabilities.names ?? {}) };
48 const executionMode = capabilities.executionMode;
49
50 const buildBaseContext = (
51 toolCallId: string,
52 sourceTool: (typeof DEFAULT_SESSION_TOOL_NAMES)[PiSessionToolName] | string,
53 originalRequest: unknown
54 ): PiBaseToolContext => ({
55 toolCallId,
56 sourceTool,
57 sessionId: capabilities.sessionId,
58 originalRequest,
59 });
60
61 const manageConnectionsForToolkits = async (
62 toolCallId: string,
63 originalRequest: unknown,
64 toolkits: string[],
65 reinitiateAll = false
66 ): Promise<{
67 value: unknown;
68 authLinks: string[];
69 context: PiConnectionManagementContext;
70 denied?: boolean;
71 }> => {
72 const connectionContext: PiConnectionManagementContext = {
73 ...buildBaseContext(toolCallId, names.manageConnections, originalRequest),
74 requestedToolkits: toolkits,
75 callbackUrl: capabilities.callbackUrl,
76 reinitiateAll,
77 };
78 const hookContext: PiManageConnectionsHookContext = {
79 ...hookControls,
80 request: { toolkits, reinitiateAll },
81 context: connectionContext,
82 };
83 const authLinks: string[] = [];
84
85 const value = await runHook(capabilities.hooks?.manageConnections, hookContext, async () => {
86 const requestedToolkits = normalizeToolkits(hookContext.request.toolkits) ?? [];
87 const shouldReinitiateAll = hookContext.request.reinitiateAll;
88 connectionContext.requestedToolkits = requestedToolkits;
89 connectionContext.reinitiateAll = shouldReinitiateAll;
90
91 const statesRaw = await capabilities.connections?.getToolkitStates?.(
92 requestedToolkits,
93 connectionContext
94 );
95 const states = normalizeToolkitStateMap(statesRaw, requestedToolkits);
96 const results: Record<string, PiConnectionToolkitResult> = {};
97
98 for (const toolkit of requestedToolkits) {
99 const state = states.get(toolkit.toLowerCase());
100 const connected = state
101 ? (capabilities.connections?.isConnected?.(state, {
102 toolkit,
103 request: connectionContext,
104 }) ?? defaultIsToolkitConnected(state))
105 : false;
106
107 if (connected && !shouldReinitiateAll) {
108 results[toolkit] = {
109 toolkit,
110 connected: true,
111 status: 'connected',
112 state,
113 };
114 continue;
115 }
116
117 if (!capabilities.connections?.authorizeToolkit) {
118 results[toolkit] = {
119 toolkit,
120 connected: false,
121 status: 'missing_authorize_handler',
122 state,
123 };
124 continue;
125 }
126
127 const authorization = await capabilities.connections.authorizeToolkit(
128 toolkit,
129 {
130 callbackUrl: capabilities.callbackUrl,
131 reinitiate: shouldReinitiateAll,
132 },
133 connectionContext
134 );
135 const handledAuthorization = await applyAuthLinkHandlers(capabilities, authorization, {
136 ...connectionContext,
137 toolkit,
138 result: authorization,
139 });
140 authLinks.push(...handledAuthorization.authLinks);
141 results[toolkit] = {
142 toolkit,
143 connected: false,
144 status: 'auth_initiated',
145 state,
146 authorization: handledAuthorization.value,
147 };
148 }
149
150 return formatDefaultConnectionResult(results);
151 });
152
153 return { value, authLinks, context: connectionContext };
154 };
155
156 const executeWithPolicy = async (
157 toolCallId: string,
158 sourceTool: (typeof DEFAULT_SESSION_TOOL_NAMES)[PiSessionToolName] | string,
159 originalRequest: unknown,
160 toolSlug: string,
161 args: Record<string, unknown>,
162 account?: string
163 ): Promise<{
164 value: unknown;
165 authLinks: string[];
166 context: PiExecuteContext;
167 denied?: boolean;
168 }> => {
169 const executeContext: PiExecuteContext = {
170 ...buildBaseContext(toolCallId, sourceTool, originalRequest),
171 toolSlug,
172 toolkit: toolkitFromToolSlug(toolSlug),
173 args,
174 account,
175 };
176 const authLinks: string[] = [];
177 const hookContext: PiExecuteHookContext = {
178 ...hookControls,
179 request: { toolSlug, args, account },
180 context: executeContext,
181 manageConnections: async (managedToolkits, manageOptions) => {
182 const managed = await manageConnectionsForToolkits(
183 toolCallId,
184 originalRequest,
185 managedToolkits,
186 manageOptions?.reinitiateAll
187 );
188 authLinks.push(...managed.authLinks);
189 return managed.value;
190 },
191 };
192
193 const value = await runHook(capabilities.hooks?.execute, hookContext, async () => {
194 const finalToolSlug = hookContext.request.toolSlug;
195 const finalArgs = hookContext.request.args;
196 const finalAccount = hookContext.request.account;
197 const finalContext: PiExecuteContext = {
198 ...executeContext,
199 toolSlug: finalToolSlug,
200 toolkit: toolkitFromToolSlug(finalToolSlug),
201 args: finalArgs,
202 account: finalAccount,
203 };
204 hookContext.context = finalContext;
205
206 const execute = hookContext.request.execute ?? capabilities.execute;
207 const session = hookContext.request.session;
208 const result = session
209 ? await session.execute(
210 finalToolSlug,
211 finalArgs,
212 finalAccount ? { account: finalAccount } : undefined
213 )
214 : await execute(
215 finalToolSlug,
216 finalArgs,
217 finalAccount ? { account: finalAccount } : undefined,
218 finalContext
219 );
220 const handledResult = await applyAuthLinkHandlers(capabilities, result, {
221 ...finalContext,
222 result,
223 });
224 authLinks.push(...handledResult.authLinks);
225 return handledResult.value;
226 });
227
228 return { value, authLinks, context: hookContext.context };
229 };
230
231 const searchTools = defineTool({
232 name: names.search,
233 label: 'Composio Search Tools',
234 description:
235 'Search Composio for tools that can perform a requested action. Search globally by default; pass toolkits only when intentionally narrowing the search.',
236 promptSnippet:
237 'Use composio_search_tools to discover exact Composio tool slugs and schemas before executing app actions.',
238 promptGuidelines: [
239 'Search Composio before inventing tool slugs or arguments.',
240 'Only pass a toolkit filter when you intentionally want to narrow search results.',
241 ],
242 parameters: Type.Object({
243 query: Type.String({
244 description: 'Natural language description of the action to perform.',
245 }),
246 toolkits: ToolkitsSchema,
247 }),
248 ...(executionMode ? { executionMode } : {}),
249 execute: async (toolCallId, params) => {
250 try {
251 const requestedToolkits = normalizeToolkits(params.toolkits);
252 const searchContext: PiSearchContext = {
253 ...buildBaseContext(toolCallId, names.search, params),
254 query: params.query,
255 requestedToolkits,
256 };
257 const hookContext: PiSearchHookContext = {
258 ...hookControls,
259 request: {
260 query: params.query,
261 ...(requestedToolkits ? { toolkits: requestedToolkits } : {}),
262 },
263 context: searchContext,
264 };
265 const authLinks: string[] = [];
266 const value = await runHook(capabilities.hooks?.search, hookContext, async () => {
267 const toolkits = normalizeToolkits(hookContext.request.toolkits);
268 hookContext.context.query = hookContext.request.query;
269 hookContext.context.requestedToolkits = toolkits;
270 const result = await capabilities.search(
271 {
272 query: hookContext.request.query,
273 ...(toolkits ? { toolkits } : {}),
274 },
275 hookContext.context
276 );
277 const handledResult = await applyAuthLinkHandlers(capabilities, result, {
278 ...hookContext.context,
279 result,
280 });
281 authLinks.push(...handledResult.authLinks);
282 return handledResult.value;
283 });
284 const transformed = await maybeTransform(capabilities, {
285 tool: 'search',
286 requestedToolkits: hookContext.context.requestedToolkits,
287 value,
288 context: hookContext.context,
289 });
290 return toPiResult(transformed, formatter, { slug: names.search, authLinks });
291 } catch (error) {
292 if (!catchErrors) throw error;
293 return toPiErrorResult(error, formatter, { slug: names.search });
294 }
295 },
296 });
297
298 const manageConnections = defineTool({
299 name: names.manageConnections,
300 label: 'Composio Manage Connections',
301 description:
302 'Check whether the user has active connections for requested toolkits and initiate Composio auth when needed.',
303 promptSnippet:
304 'Use composio_manage_connections when a searched tool requires a missing app connection.',
305 promptGuidelines: [
306 'When an app connection is missing, call composio_manage_connections with the toolkit slug.',
307 'Never ask the user for OAuth secrets or API keys directly.',
308 ],
309 parameters: Type.Object({
310 toolkits: Type.Array(
311 Type.String({ description: 'Toolkit slugs to check/connect, e.g. github, gmail.' })
312 ),
313 reinitiate_all: Type.Optional(
314 Type.Boolean({ description: 'Force reconnection even if active connections exist.' })
315 ),
316 }),
317 ...(executionMode ? { executionMode } : {}),
318 execute: async (toolCallId, params) => {
319 const toolkits = normalizeToolkits(params.toolkits) ?? [];
320 try {
321 const managed = await manageConnectionsForToolkits(
322 toolCallId,
323 params,
324 toolkits,
325 params.reinitiate_all ?? false
326 );
327 const transformed = await maybeTransform(capabilities, {
328 tool: 'manageConnections',
329 requestedToolkits: toolkits,
330 value: managed.value,
331 context: managed.context,
332 });
333 return toPiResult(transformed, formatter, {
334 slug: names.manageConnections,
335 authLinks: managed.authLinks,
336 denied: managed.denied,
337 });
338 } catch (error) {
339 if (!catchErrors) throw error;
340 return toPiErrorResult(error, formatter, { slug: names.manageConnections });
341 }
342 },
343 });
344
345 const executeTool = defineTool({
346 name: names.execute,
347 label: 'Composio Execute Tool',
348 description:
349 'Execute an exact Composio tool slug using the configured Composio execution capability. Use search first so the slug and arguments match the schema.',
350 promptSnippet:
351 'Use composio_execute_tool to execute an exact Composio tool slug returned by composio_search_tools.',
352 promptGuidelines: [
353 'Always use exact tool slugs and schema-compliant arguments.',
354 'For missing connections, use composio_manage_connections instead of asking for credentials.',
355 ],
356 parameters: Type.Object({
357 toolSlug: Type.String({
358 description: 'Exact Composio tool slug, e.g. GITHUB_CREATE_ISSUE.',
359 }),
360 arguments: optionalRecordSchema('Tool arguments matching the searched schema.'),
361 account: Type.Optional(
362 Type.String({
363 description:
364 'Optional account selector for multi-account sessions. Use connected account id or alias when required.',
365 })
366 ),
367 }),
368 ...(executionMode ? { executionMode } : {}),
369 prepareArguments: args =>
370 normalizeToolArguments(args, names.execute) as {
371 toolSlug: string;
372 arguments?: Record<string, unknown>;
373 account?: string;
374 },
375 execute: async (toolCallId, params) => {
376 const toolSlug = params.toolSlug.trim();
377 const args = params.arguments ?? {};
378 try {
379 const executed = await executeWithPolicy(
380 toolCallId,
381 names.execute,
382 params,
383 toolSlug,
384 args,
385 params.account
386 );
387 const transformed = await maybeTransform(capabilities, {
388 tool: 'execute',
389 requestedToolkits: toolkitFromToolSlug(executed.context.toolSlug)
390 ? [toolkitFromToolSlug(executed.context.toolSlug)!]
391 : undefined,
392 value: executed.value,
393 context: executed.context,
394 });
395 return toPiResult(transformed, formatter, {
396 slug: executed.context.toolSlug || names.execute,
397 authLinks: executed.authLinks,
398 denied: executed.denied,
399 });
400 } catch (error) {
401 if (!catchErrors) throw error;
402 return toPiErrorResult(error, formatter, { slug: toolSlug || names.execute });
403 }
404 },
405 });
406
407 if (!capabilities.includeWorkbenchTools) {
408 return [searchTools, manageConnections, executeTool];
409 }
410
411 const remoteWorkbench = defineTool({
412 name: names.remoteWorkbench,
413 label: 'Composio Remote Workbench',
414 description:
415 'Execute Python code inside the Composio remote workbench for this Tool Router session. Use it for remote files, bulk processing, large tool outputs, and Composio-authenticated scripting.',
416 promptSnippet:
417 'Use composio_remote_workbench for Python scripting in the Composio remote sandbox when data is large, stored in remote files, or needs session-authenticated tool/proxy helpers.',
418 promptGuidelines: [
419 'Use composio_remote_workbench for large data processing or remote workbench files; do not use it for tiny inline transformations.',
420 'Split long-running work into small cells and save checkpoints in the workbench filesystem.',
421 ],
422 parameters: Type.Object({
423 code_to_execute: Type.String({
424 description:
425 'Python code to run in the persistent Composio remote workbench. Keep cells focused and avoid long-running jobs.',
426 }),
427 timeout: Type.Optional(
428 Type.Number({
429 minimum: 1,
430 maximum: 780,
431 description:
432 'Maximum seconds to allow execution. Defaults to the session/backend workbench timeout.',
433 })
434 ),
435 thought: Type.Optional(
436 Type.String({ description: 'Concise objective for why this workbench cell is needed.' })
437 ),
438 file_path: Type.Optional(
439 Type.String({
440 description: 'Remote workbench path/glob to analyze when processing a file.',
441 })
442 ),
443 disabled_tools: Type.Optional(
444 Type.Array(Type.String({ description: 'Tool slugs to disable for this workbench call.' }))
445 ),
446 session_id: Type.Optional(
447 Type.String({
448 description:
449 'Workbench workflow session id. Defaults to the Composio Tool Router session id.',
450 })
451 ),
452 }),
453 ...(executionMode ? { executionMode } : {}),
454 execute: async (toolCallId, params) => {
455 try {
456 const request: PiRemoteWorkbenchRequest = {
457 ...params,
458 ...(params.session_id || capabilities.sessionId
459 ? { session_id: params.session_id ?? capabilities.sessionId }
460 : {}),
461 };
462 const hookContext: PiRemoteWorkbenchHookContext = {
463 ...hookControls,
464 request,
465 context: {
466 ...buildBaseContext(toolCallId, names.remoteWorkbench, params),
467 toolSlug: 'COMPOSIO_REMOTE_WORKBENCH',
468 args: request,
469 },
470 };
471 const authLinks: string[] = [];
472 const details: Pick<PiToolDetails, 'denied'> = {};
473 const value = await runHook(capabilities.hooks?.remoteWorkbench, hookContext, async () => {
474 const executed = await executeWithPolicy(
475 toolCallId,
476 names.remoteWorkbench,
477 params,
478 'COMPOSIO_REMOTE_WORKBENCH',
479 hookContext.request
480 );
481 authLinks.push(...executed.authLinks);
482 details.denied = executed.denied;
483 hookContext.context = executed.context;
484 return executed.value;
485 });
486 const transformed = await maybeTransform(capabilities, {
487 tool: 'remoteWorkbench',
488 value,
489 context: hookContext.context,
490 });
491 return toPiResult(transformed, formatter, {
492 slug: hookContext.context.toolSlug,
493 authLinks,
494 denied: details.denied,
495 });
496 } catch (error) {
497 if (!catchErrors) throw error;
498 return toPiErrorResult(error, formatter, { slug: 'COMPOSIO_REMOTE_WORKBENCH' });
499 }
500 },
501 });
502
503 const remoteBash = defineTool({
504 name: names.remoteBash,
505 label: 'Composio Remote Bash',
506 description:
507 'Execute a bash command inside the Composio remote workbench for this Tool Router session.',
508 promptSnippet:
509 'Use composio_remote_bash to inspect or manipulate files in the Composio remote workbench filesystem.',
510 promptGuidelines: [
511 'Use composio_remote_bash for filesystem inspection in the remote workbench, especially for truncated output files.',
512 'Keep commands short and non-interactive.',
513 ],
514 parameters: Type.Object({
515 command: Type.String({
516 description: 'Bash command to execute in the Composio remote workbench.',
517 }),
518 session_id: Type.Optional(
519 Type.String({
520 description:
521 'Workbench workflow session id. Defaults to the Composio Tool Router session id.',
522 })
523 ),
524 }),
525 ...(executionMode ? { executionMode } : {}),
526 execute: async (toolCallId, params) => {
527 try {
528 const request: PiRemoteBashRequest = {
529 ...params,
530 ...(params.session_id || capabilities.sessionId
531 ? { session_id: params.session_id ?? capabilities.sessionId }
532 : {}),
533 };
534 const hookContext: PiRemoteBashHookContext = {
535 ...hookControls,
536 request,
537 context: {
538 ...buildBaseContext(toolCallId, names.remoteBash, params),
539 toolSlug: 'COMPOSIO_REMOTE_BASH_TOOL',
540 args: request,
541 },
542 };
543 const authLinks: string[] = [];
544 const details: Pick<PiToolDetails, 'denied'> = {};
545 const value = await runHook(capabilities.hooks?.remoteBash, hookContext, async () => {
546 const executed = await executeWithPolicy(
547 toolCallId,
548 names.remoteBash,
549 params,
550 'COMPOSIO_REMOTE_BASH_TOOL',
551 hookContext.request
552 );
553 authLinks.push(...executed.authLinks);
554 details.denied = executed.denied;
555 hookContext.context = executed.context;
556 return executed.value;
557 });
558 const transformed = await maybeTransform(capabilities, {
559 tool: 'remoteBash',
560 value,
561 context: hookContext.context,
562 });
563 return toPiResult(transformed, formatter, {
564 slug: hookContext.context.toolSlug,
565 authLinks,
566 denied: details.denied,
567 });
568 } catch (error) {
569 if (!catchErrors) throw error;
570 return toPiErrorResult(error, formatter, { slug: 'COMPOSIO_REMOTE_BASH_TOOL' });
571 }
572 },
573 });
574
575 return [searchTools, manageConnections, executeTool, remoteWorkbench, remoteBash];
576 };