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 502 lines 17.8 KB
Raw
1 import { Effect, Option } from 'effect';
2 import { CommandSurface } from 'src/commands/surface';
3 import { retryAdviceFor } from 'src/effects/retry-advice';
4 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
5 import { appendCliSessionHistory } from 'src/services/cli-session-artifacts';
6 import {
7 getFreshConsumerConnectedToolkitsFromCache,
8 refreshConsumerConnectedToolkitsCache,
9 } from 'src/services/consumer-short-term-cache';
10 import { logToolDebug } from 'src/services/runtime-debug-logger';
11 import type { TerminalUI } from 'src/services/terminal-ui';
12 import {
13 getOrFetchToolInputDefinition,
14 invalidateToolInputDefinition,
15 ToolInputValidationError,
16 } from 'src/services/tool-input-validation';
17 import { detectInBandWarning } from 'src/services/tools-executor';
18 import type { ToolExecuteParams, ToolsExecutor } from 'src/services/tools-executor';
19 import { escapeTerminalText } from 'src/ui/escape-terminal-text';
20 import { redact } from 'src/ui/redact';
21 import {
22 resolveExecuteContext,
23 resolveSchemaContext,
24 toolkitProjectScope,
25 type ResolvedExecuteContext,
26 type RunToolsExecuteParams,
27 } from './tools.execute.context';
28 import { perfDebugLog } from './tools.execute.debug';
29 import { invalidArguments, ReportedToolExecutionError } from './tools.execute.errors';
30 import {
31 emitExecuteFailureTelemetry,
32 handleExecutionError,
33 printExecuteRetryAdvice,
34 } from './tools.execute.failure';
35 import {
36 ciRedactReplacer,
37 connectionTips,
38 describeStoredOutputSize,
39 emitCachedSchema,
40 executionSuccessSuffix,
41 writeExecuteStdout,
42 type DryRunSummary,
43 } from './tools.execute.format';
44 import { prepareExecuteOutput } from './tools.execute.output';
45 import { runParallelFromCommand } from './tools.execute.parallel';
46 import { checkDryRunArguments, validateToolInputBeforeExecute } from './tools.execute.validation';
47
48 const runConnectedToolkitFailFast = (params: {
49 readonly slug: string;
50 readonly surface: 'root' | 'dev';
51 readonly ui: TerminalUI;
52 readonly resolvedProject: ResolvedExecuteContext['resolvedProject'];
53 readonly resolvedUserId: string;
54 readonly skipConnectionCheck: boolean;
55 readonly skipChecks: boolean;
56 }) =>
57 Effect.gen(function* () {
58 if (params.skipConnectionCheck || params.skipChecks) {
59 yield* perfDebugLog('execute.connected_toolkits.skipped', {
60 slug: params.slug,
61 reason: params.skipChecks ? 'skip-checks' : 'skip-connection-check',
62 });
63 return;
64 }
65 if (params.resolvedProject.projectType !== 'CONSUMER') return;
66
67 yield* perfDebugLog('execute.connected_toolkits.refresh_start', {
68 slug: params.slug,
69 orgId: params.resolvedProject.orgId,
70 consumerUserId: params.resolvedUserId,
71 });
72 yield* refreshConsumerConnectedToolkitsCache({
73 orgId: params.resolvedProject.orgId,
74 consumerUserId: params.resolvedUserId,
75 }).pipe(
76 Effect.tap(() =>
77 perfDebugLog('execute.connected_toolkits.refresh_end', {
78 slug: params.slug,
79 orgId: params.resolvedProject.orgId,
80 consumerUserId: params.resolvedUserId,
81 successful: true,
82 })
83 ),
84 Effect.catch(() =>
85 perfDebugLog('execute.connected_toolkits.refresh_end', {
86 slug: params.slug,
87 orgId: params.resolvedProject.orgId,
88 consumerUserId: params.resolvedUserId,
89 successful: false,
90 })
91 ),
92 Effect.forkDetach,
93 Effect.asVoid
94 );
95
96 const toolkit = yield* toolkitFromToolSlug(
97 params.slug,
98 toolkitProjectScope(params.resolvedProject)
99 );
100 if (!toolkit) return;
101
102 const cachedToolkits = yield* getFreshConsumerConnectedToolkitsFromCache({
103 orgId: params.resolvedProject.orgId,
104 consumerUserId: params.resolvedUserId,
105 });
106 yield* perfDebugLog(
107 Option.isSome(cachedToolkits)
108 ? 'execute.connected_toolkits.cache_hit'
109 : 'execute.connected_toolkits.cache_miss',
110 {
111 slug: params.slug,
112 toolkit,
113 orgId: params.resolvedProject.orgId,
114 consumerUserId: params.resolvedUserId,
115 cachedToolkits: Option.isSome(cachedToolkits) ? cachedToolkits.value : undefined,
116 }
117 );
118
119 if (Option.isSome(cachedToolkits) && !cachedToolkits.value.includes(toolkit)) {
120 yield* perfDebugLog('execute.connected_toolkits.fail_fast', {
121 slug: params.slug,
122 toolkit,
123 orgId: params.resolvedProject.orgId,
124 consumerUserId: params.resolvedUserId,
125 });
126 const message = `Toolkit "${toolkit}" is not connected for this user (cached within the last 5 minutes). If you just connected the account, use --skip-connection-check.`;
127 yield* params.ui.log.error(message);
128 yield* params.ui.note(
129 connectionTips({ toolkit, toolSlug: params.slug, surface: params.surface }),
130 'Tips'
131 );
132 yield* writeExecuteStdout(
133 params.ui,
134 JSON.stringify(
135 {
136 successful: false,
137 error: message,
138 slug: params.slug,
139 },
140 ciRedactReplacer,
141 2
142 )
143 );
144 return yield* new ReportedToolExecutionError({
145 reason: 'connection_check',
146 toolSlug: params.slug,
147 message,
148 });
149 }
150 });
151
152 const executeSessionHistoryScope = (resolvedProject: ResolvedExecuteContext['resolvedProject']) =>
153 resolvedProject.projectType === 'CONSUMER'
154 ? {
155 orgId: resolvedProject.orgId,
156 consumerUserId: resolvedProject.consumerUserId,
157 }
158 : {};
159
160 const runExecuteWithSpinner = (params: {
161 readonly slug: string;
162 readonly surface: 'root' | 'dev';
163 readonly projectMode: 'consumer' | 'developer';
164 readonly dryRun: boolean;
165 readonly ui: TerminalUI;
166 readonly executor: ToolsExecutor;
167 readonly resolvedProject: ResolvedExecuteContext['resolvedProject'];
168 readonly args: Record<string, unknown>;
169 readonly resolvedUserId: string;
170 readonly executeParams: ToolExecuteParams;
171 readonly executeOutputDir?: string;
172 readonly skipToolParamsCheck: boolean;
173 readonly skipChecks: boolean;
174 }) =>
175 Effect.gen(function* () {
176 const verificationDisabled = params.skipChecks || params.skipToolParamsCheck;
177
178 yield* params.ui.useMakeSpinner(`Executing tool "${params.slug}"...`, spinner =>
179 Effect.gen(function* () {
180 if (params.dryRun) {
181 const definition = yield* checkDryRunArguments({
182 slug: params.slug,
183 args: params.args,
184 projectScope: {
185 orgId: params.resolvedProject.orgId,
186 projectId: params.resolvedProject.projectId,
187 },
188 verificationDisabled,
189 }).pipe(
190 Effect.tapError(error =>
191 emitExecuteFailureTelemetry({
192 toolSlug: params.slug,
193 args: params.args,
194 error,
195 surface: params.surface,
196 projectMode: params.projectMode,
197 stage: 'dry_run',
198 projectScope: toolkitProjectScope(params.resolvedProject),
199 })
200 )
201 );
202 const summary: DryRunSummary = {
203 successful: true,
204 dryRun: true,
205 slug: params.slug,
206 arguments: params.args,
207 userId: params.resolvedUserId,
208 schemaPath: definition?.schemaPath,
209 schemaVersion: definition?.version,
210 };
211 yield* spinner.stop('Dry run successful');
212 yield* params.ui.log.message(
213 verificationDisabled
214 ? 'No tool was executed. Local validation was skipped.'
215 : 'No tool was executed. Arguments were validated locally only.'
216 );
217 yield* writeExecuteStdout(params.ui, JSON.stringify(summary, ciRedactReplacer, 2));
218 yield* appendCliSessionHistory({
219 ...executeSessionHistoryScope(params.resolvedProject),
220 entry: {
221 command: 'execute',
222 status: 'dry-run',
223 slug: params.slug,
224 arguments: params.args,
225 },
226 }).pipe(Effect.catch(() => Effect.void));
227 return;
228 }
229
230 yield* perfDebugLog('execute.tool_call.start', { slug: params.slug });
231 const validateArgs = verificationDisabled
232 ? Effect.void
233 : validateToolInputBeforeExecute({
234 slug: params.slug,
235 args: params.args,
236 resolvedProject: params.resolvedProject,
237 });
238 const result = yield* validateArgs.pipe(
239 Effect.andThen(params.executor.execute(params.slug, params.executeParams)),
240 Effect.matchEffect({
241 onFailure: error =>
242 Effect.gen(function* () {
243 yield* logToolDebug('execute_result', { slug: params.slug, result: error });
244 yield* perfDebugLog('execute.tool_call.end', {
245 slug: params.slug,
246 successful: false,
247 });
248 // The validation error points the user at the cached schema, so
249 // it has to stay on disk.
250 if (!(error instanceof ToolInputValidationError)) {
251 yield* invalidateToolInputDefinition(params.slug).pipe(
252 Effect.catch(() => Effect.void)
253 );
254 }
255 yield* spinner.error();
256 const summary = yield* handleExecutionError(params.ui, error, {
257 toolSlug: params.slug,
258 args: params.args,
259 surface: params.surface,
260 projectMode: params.projectMode,
261 stage: 'execution',
262 projectScope: toolkitProjectScope(params.resolvedProject),
263 });
264 // Whether the request can be sent again as it is: `"retry": "safe"` (exit 75) or
265 // `"retry": "check-first"` when it may have run before it failed.
266 const retry = Option.getOrUndefined(retryAdviceFor(error));
267 if (retry !== undefined) {
268 yield* printExecuteRetryAdvice(params.ui, retry, params.surface);
269 }
270 yield* writeExecuteStdout(
271 params.ui,
272 JSON.stringify(
273 { successful: false, ...summary, ...(retry === undefined ? {} : { retry }) },
274 ciRedactReplacer,
275 2
276 )
277 );
278 yield* appendCliSessionHistory({
279 ...executeSessionHistoryScope(params.resolvedProject),
280 entry: {
281 command: 'execute',
282 status: 'error',
283 slug: params.slug,
284 arguments: params.args,
285 error: summary.error,
286 },
287 }).pipe(Effect.catch(() => Effect.void));
288 return yield* new ReportedToolExecutionError({
289 reason: 'execution_failed',
290 toolSlug: params.slug,
291 message: summary.error,
292 ...(retry === 'safe' ? { retryable: true } : {}),
293 });
294 }),
295 onSuccess: result =>
296 Effect.gen(function* () {
297 yield* logToolDebug('execute_result', { slug: params.slug, result });
298 yield* perfDebugLog('execute.tool_call.end', {
299 slug: params.slug,
300 successful: true,
301 });
302 return result;
303 }),
304 })
305 );
306 if (!result.successful) {
307 yield* invalidateToolInputDefinition(params.slug).pipe(Effect.catch(() => Effect.void));
308 const logId = result.logId
309 ? ` (logId: ${escapeTerminalText(redact({ value: result.logId, prefix: 'log_' }))})`
310 : '';
311 yield* spinner.error(`Execution failed${logId}`);
312
313 const summary = yield* handleExecutionError(params.ui, result.error ?? result, {
314 toolSlug: params.slug,
315 args: params.args,
316 surface: params.surface,
317 projectMode: params.projectMode,
318 stage: 'execution',
319 logId: result.logId,
320 projectScope: toolkitProjectScope(params.resolvedProject),
321 });
322 yield* writeExecuteStdout(params.ui, JSON.stringify(result, ciRedactReplacer, 2));
323 return yield* new ReportedToolExecutionError({
324 reason: 'execution_failed',
325 toolSlug: params.slug,
326 message: summary.error,
327 });
328 }
329
330 yield* spinner.stop(`Execution successful${executionSuccessSuffix(result)}`);
331 const inBandWarning = detectInBandWarning(result.data);
332 if (inBandWarning) {
333 yield* params.ui.log.warn(
334 `The tool executed successfully but the response may contain an error: ${escapeTerminalText(inBandWarning)}`
335 );
336 }
337 const output = yield* prepareExecuteOutput(params.slug, result, params.executeOutputDir);
338 if (output.kind === 'file') {
339 yield* params.ui.log.message(
340 `Response stored in ${output.summary.outputFilePath} (${describeStoredOutputSize(output.summary)})`
341 );
342 yield* writeExecuteStdout(params.ui, JSON.stringify(output.summary, ciRedactReplacer, 2));
343 yield* appendCliSessionHistory({
344 ...executeSessionHistoryScope(params.resolvedProject),
345 entry: {
346 command: 'execute',
347 status: 'success',
348 slug: params.slug,
349 arguments: params.args,
350 storedInFile: true,
351 outputFilePath: output.summary.outputFilePath,
352 tokenCount: output.summary.tokenCount,
353 sizeBytes: output.summary.sizeBytes,
354 logId: result.logId,
355 },
356 }).pipe(Effect.catch(() => Effect.void));
357 return;
358 }
359
360 yield* writeExecuteStdout(params.ui, output.json);
361 yield* appendCliSessionHistory({
362 ...executeSessionHistoryScope(params.resolvedProject),
363 entry: {
364 command: 'execute',
365 status: 'success',
366 slug: params.slug,
367 arguments: params.args,
368 storedInFile: false,
369 logId: result.logId,
370 },
371 }).pipe(Effect.catch(() => Effect.void));
372 })
373 );
374 });
375
376 const runToolsExecute = (params: RunToolsExecuteParams) =>
377 Effect.gen(function* () {
378 if (params.getSchema) {
379 const context = yield* resolveSchemaContext(params);
380 const definition = yield* getOrFetchToolInputDefinition(params.slug, {
381 orgId: context.resolvedProject.orgId,
382 projectId: context.resolvedProject.projectId,
383 }).pipe(
384 Effect.tapError(error =>
385 emitExecuteFailureTelemetry({
386 toolSlug: params.slug,
387 args: {},
388 error,
389 surface: params.surface,
390 projectMode: params.projectMode,
391 stage: 'schema_fetch',
392 projectScope: toolkitProjectScope(context.resolvedProject),
393 })
394 )
395 );
396 yield* emitCachedSchema(context.ui, params.slug, definition);
397 return;
398 }
399
400 const context = yield* resolveExecuteContext(params);
401
402 yield* runConnectedToolkitFailFast({
403 slug: params.slug,
404 surface: params.surface,
405 ui: context.ui,
406 resolvedProject: context.resolvedProject,
407 resolvedUserId: context.resolvedUserId,
408 skipConnectionCheck: params.skipConnectionCheck,
409 skipChecks: params.skipChecks,
410 });
411 yield* logToolDebug('execute_params', {
412 slug: params.slug,
413 userId: context.resolvedUserId,
414 connectedAccountId: context.selectedConnectedAccountId,
415 arguments: context.args,
416 projectId: context.resolvedProject.projectId,
417 orgId: context.resolvedProject.orgId,
418 });
419 yield* perfDebugLog('execute.prepare', {
420 slug: params.slug,
421 surface: params.surface,
422 projectMode: params.projectMode,
423 });
424 yield* runExecuteWithSpinner({
425 slug: params.slug,
426 surface: params.surface,
427 projectMode: params.projectMode,
428 dryRun: params.dryRun,
429 ui: context.ui,
430 executor: context.executor,
431 resolvedProject: context.resolvedProject,
432 args: context.args,
433 resolvedUserId: context.resolvedUserId,
434 executeParams: context.executeParams,
435 skipToolParamsCheck: params.skipToolParamsCheck,
436 skipChecks: params.skipChecks,
437 });
438 });
439
440 export type ToolsExecuteParams = {
441 readonly slug: string;
442 readonly additionalSlugs: ReadonlyArray<string>;
443 readonly parallel: boolean;
444 readonly data: Option.Option<string>;
445 readonly file: Option.Option<string>;
446 readonly account: Option.Option<string>;
447 readonly getSchema: boolean;
448 readonly dryRun: boolean;
449 readonly skipConnectionCheck: boolean;
450 readonly skipToolParamsCheck: boolean;
451 readonly skipChecks: boolean;
452 };
453
454 /**
455 * The handler of both `execute` (root tree, the consumer project) and `dev playground-execute`
456 * (`dev` tree, the developer project, with the `dev` group's `--user-id` and `--project-name`).
457 */
458 export const runToolsExecuteCommand = ({
459 slug,
460 additionalSlugs,
461 parallel,
462 data,
463 file,
464 account,
465 getSchema,
466 dryRun,
467 skipConnectionCheck,
468 skipToolParamsCheck,
469 skipChecks,
470 }: ToolsExecuteParams) =>
471 Effect.gen(function* () {
472 const { tree, projectName } = yield* CommandSurface;
473 const projectMode = tree === 'root' ? 'consumer' : 'developer';
474 if (parallel) {
475 return yield* runParallelFromCommand({
476 surface: tree,
477 projectMode,
478 getSchema,
479 dryRun,
480 skipConnectionCheck,
481 skipToolParamsCheck,
482 skipChecks,
483 });
484 }
485 if (additionalSlugs.length > 0) {
486 return yield* invalidArguments('Additional tool slugs require --parallel.');
487 }
488 return yield* runToolsExecute({
489 slug,
490 data,
491 file,
492 account,
493 projectName,
494 surface: tree,
495 projectMode,
496 getSchema,
497 dryRun,
498 skipConnectionCheck,
499 skipToolParamsCheck,
500 skipChecks,
501 });
502 });