@devries-cameron20 / composio Mirror · read-only
Fork 0

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

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
ts 402 lines 14.5 KB
Raw
1 import * as FileSystem from 'effect/FileSystem';
2 import * as Path from 'effect/Path';
3 import { Context, Effect, Layer } from 'effect';
4 import {
5 isComposioError,
6 type ComposioClientShape,
7 type ComposioError,
8 } from '@composio/client/effect';
9 import type {
10 SessionExecuteResponse,
11 SessionExecuteMetaResponse,
12 } from '@composio/client/resources/tool-router';
13 import { ComposioClientSingleton, type ToolkitProjectScope } from 'src/services/composio-clients';
14 import {
15 createToolRouterSessionFromContext,
16 resolveToolRouterSessionContext,
17 type ToolRouterSessionContext,
18 } from 'src/effects/create-tool-router-session';
19 import {
20 DashboardToolExecution,
21 type DashboardToolExecutionError,
22 type DashboardToolExecutionShape,
23 } from 'src/services/dashboard-tool-execution';
24 import { gateToolExecution, type PermissionGateResult } from 'src/services/tool-permissions';
25 import {
26 ComposioNoActiveConnectionError,
27 mapComposioError,
28 } from 'src/services/composio-error-overrides';
29 import { getOrFetchToolInputDefinition } from 'src/services/tool-input-validation';
30 import type { CliDebugFlags } from 'src/services/runtime-flags';
31 import {
32 readRunStagedFiles,
33 ToolFileUploadError,
34 uploadToolInputFiles,
35 } from 'src/services/tool-file-uploads';
36 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
37 import { ToolkitSlugCatalog } from 'src/services/toolkit-slug-catalog';
38 import { APP_CONFIG } from 'src/config';
39 import { isMetaToolSlug } from 'src/utils/meta-tool-slugs';
40 import { toolInputRequiredError, type ToolInputRequiredError } from 'src/utils/tool-input-required';
41 import type { NodeOs } from 'src/services/node-os';
42 import type { NodeProcess } from 'src/services/node-process';
43 import type { ComposioUserContext } from 'src/services/user-context';
44 import type { ComposioToolkitsRepository } from 'src/services/composio-clients';
45 import type { TerminalUI } from 'src/services/terminal-ui';
46 import type { ComposioCliUserConfig } from 'src/services/cli-user-config';
47
48 /**
49 * Where the execution itself is sent. Connection lookups, the permission gate
50 * and file uploads go to the backend either way.
51 */
52 export type ToolExecutionTarget =
53 | { readonly kind: 'backend' }
54 /** `orgId` is the organization the Dashboard resolves the consumer project from. */
55 | { readonly kind: 'dashboard'; readonly orgId: string };
56
57 /**
58 * Parameters accepted by the Tool Router-based executor.
59 */
60 export interface ToolExecuteParams {
61 readonly userId: string;
62 /** Chosen by the command, never inferred by the executor. */
63 readonly target: ToolExecutionTarget;
64 readonly arguments: Record<string, unknown>;
65 readonly client?: ComposioClientShape;
66 readonly connectedAccounts?: Record<string, string>;
67 /**
68 * The org/project the command resolved. The executor's tool-schema lookup
69 * keys its memoized `get_latest_version` on this, so it has to match what
70 * the command's own version check passed or the two never share a request.
71 */
72 readonly projectScope?: {
73 readonly orgId?: string;
74 readonly projectId?: string;
75 };
76 readonly cacheScope?: {
77 readonly orgId: string;
78 readonly projectId: string;
79 readonly consumerUserId: string;
80 };
81 }
82
83 /**
84 * The project custom toolkits are listed for: the command's resolved one when
85 * it handed in both ids, otherwise whatever the project context resolves.
86 */
87 const toolkitProjectScope = ({
88 projectScope,
89 }: ToolExecuteParams): ToolkitProjectScope | undefined =>
90 projectScope?.orgId && projectScope.projectId
91 ? { orgId: projectScope.orgId, projectId: projectScope.projectId }
92 : undefined;
93
94 /**
95 * Normalized response that matches the shape consumers expect.
96 */
97 export interface ToolExecuteResponse {
98 readonly successful: boolean;
99 readonly data: Record<string, unknown>;
100 readonly error: string | null;
101 readonly logId: string;
102 readonly permissionApproval?: NonNullable<PermissionGateResult>['approvalStatus'];
103 readonly instantCharge?: InstantCharge;
104 }
105
106 /** Charge billed to the org when the call ran on a Composio instant account. */
107 export interface InstantCharge {
108 readonly amount: string;
109 readonly currency: 'USD';
110 readonly chargedBy: 'composio';
111 }
112
113 export interface ToolsExecutor {
114 readonly execute: (
115 slug: string,
116 params: ToolExecuteParams
117 ) => Effect.Effect<
118 ToolExecuteResponse,
119 unknown,
120 | FileSystem.FileSystem
121 | Path.Path
122 | NodeOs
123 | NodeProcess
124 | ComposioUserContext
125 | ComposioClientSingleton
126 | ComposioToolkitsRepository
127 | ComposioCliUserConfig
128 | TerminalUI
129 // Tool-schema resolution emits `--tool-debug` diagnostics, whose flag values the caller owns.
130 | CliDebugFlags
131 >;
132 }
133
134 export const ToolsExecutor = Context.Service<ToolsExecutor>('services/ToolsExecutor');
135
136 /**
137 * Whether an execution answer describes a tool that ran and succeeded.
138 *
139 * `result_type` decides: a `failed` execution is not successful even when its
140 * `error` is `null` or empty. `@composio/core` applies the same rule to
141 * session executions.
142 */
143 export const isExecutionSuccessful = (raw: {
144 readonly result_type: 'completed' | 'failed' | 'blocked';
145 }): boolean => raw.result_type === 'completed';
146
147 /** A Tool Router answer that carries a result rather than a request for more input. */
148 type ExecutedSessionResponse = Exclude<
149 SessionExecuteResponse | SessionExecuteMetaResponse,
150 { result_type: 'input_required' }
151 >;
152
153 /** Sends the prepared arguments to where the tool runs. Called once per invocation. */
154 type ToolExecutionSend = (
155 arguments_: Record<string, unknown>
156 ) => Effect.Effect<
157 ExecutedSessionResponse,
158 ComposioError | ToolInputRequiredError | DashboardToolExecutionError,
159 FileSystem.FileSystem | Path.Path | NodeOs
160 >;
161
162 const toInstantCharge = (raw: ExecutedSessionResponse): InstantCharge | undefined => {
163 if (!raw.instant_charge) return undefined;
164 return {
165 amount: raw.instant_charge.amount,
166 currency: raw.instant_charge.currency,
167 chargedBy: raw.instant_charge.charged_by,
168 };
169 };
170
171 /**
172 * Normalize the raw Tool Router response into the shape the CLI commands expect.
173 */
174 export const normalizeResponse = (
175 raw: ExecutedSessionResponse,
176 permissionGateResult?: PermissionGateResult
177 ): ToolExecuteResponse => {
178 // A call a session hook blocked carries the hook's message instead of a
179 // result. Like `@composio/core`, the CLI reports it as a failed call with
180 // that message.
181 const outcome =
182 raw.result_type === 'blocked'
183 ? { data: {}, error: raw.message, logId: raw.log_id ?? '' }
184 : { data: raw.data, error: raw.error, logId: raw.log_id };
185 const response: ToolExecuteResponse = {
186 successful: isExecutionSuccessful(raw),
187 ...outcome,
188 ...(permissionGateResult?.approvalStatus
189 ? { permissionApproval: permissionGateResult.approvalStatus }
190 : {}),
191 };
192 const instantCharge = toInstantCharge(raw);
193 if (!instantCharge) return response;
194 return { ...response, instantCharge };
195 };
196
197 /**
198 * Detect in-band error hints in tool response data.
199 *
200 * Some external services (e.g. Metabase) return HTTP 200 with the error
201 * embedded inside the data payload. This does NOT override `successful` —
202 * the tool execution itself succeeded — but returns a warning message so
203 * the CLI display layer can surface it to the user.
204 */
205 export const detectInBandWarning = (
206 data: Record<string, unknown> | null | undefined
207 ): string | null => {
208 if (data == null) return null;
209
210 if (typeof data.status === 'string') {
211 const status = data.status.toLowerCase();
212 if (status === 'failed' || status === 'error') {
213 if (typeof data.error === 'string') return data.error;
214 if (typeof data.message === 'string') return data.message;
215 return `Tool response contains status: ${data.status}`;
216 }
217 }
218
219 if (data.successfull === false || data.successful === false) {
220 if (typeof data.error === 'string') return data.error;
221 if (typeof data.message === 'string') return data.message;
222 return 'Tool response indicates unsuccessful execution';
223 }
224 return null;
225 };
226
227 /**
228 * The backend transport: creates the Tool Router session and returns the
229 * handle that executes on it. One session per invocation — CLI runs one tool
230 * per process.
231 */
232 const createBackendSend = (
233 client: ComposioClientShape,
234 userId: string,
235 slug: string,
236 sessionContext: ToolRouterSessionContext
237 ) =>
238 createToolRouterSessionFromContext(client, userId, sessionContext).pipe(
239 Effect.map(
240 ({ sessionId }): ToolExecutionSend =>
241 arguments_ =>
242 Effect.gen(function* () {
243 // An execution is not `idempotent`, so it is sent once: a retry after the backend
244 // already acted duplicates the side effect (e.g. sends the same email twice). The
245 // response is not validated either, for the same reason.
246 const raw: SessionExecuteResponse | SessionExecuteMetaResponse = yield* isMetaToolSlug(
247 slug
248 )
249 ? client.toolRouter.session.executeMeta(sessionId, { slug, arguments: arguments_ })
250 : client.toolRouter.session.execute(sessionId, {
251 tool_slug: slug,
252 arguments: arguments_,
253 });
254 if (raw.result_type === 'input_required') {
255 return yield* toolInputRequiredError(`Tool ${slug}`, raw);
256 }
257 return raw;
258 })
259 )
260 );
261
262 /**
263 * The Dashboard transport: the Dashboard creates the session and resolves the
264 * user itself, so the CLI sends no session settings, only the account it
265 * resolved for this tool's toolkit.
266 */
267 const createDashboardSend =
268 (
269 dashboard: DashboardToolExecutionShape,
270 slug: string,
271 orgId: string,
272 connectedAccounts: ToolExecuteParams['connectedAccounts']
273 ): ToolExecutionSend =>
274 arguments_ => {
275 const request = { slug, arguments: arguments_, orgId };
276 if (isMetaToolSlug(slug)) return dashboard.executeMeta(request);
277 const [account] = Object.values(connectedAccounts ?? {});
278 return dashboard.execute({ ...request, account });
279 };
280
281 /**
282 * What has to happen before the call is sent, whichever transport sends it:
283 * the permission gate, then the arguments with their file inputs uploaded.
284 */
285 const prepareToolExecution = (
286 client: ComposioClientShape,
287 slug: string,
288 params: ToolExecuteParams,
289 { permissionSnapshot, connectedAccounts, connectedAccountWordIds }: ToolRouterSessionContext
290 ) =>
291 Effect.gen(function* () {
292 const toolkitSlug = yield* toolkitFromToolSlug(slug, toolkitProjectScope(params));
293 const permissionGateResult = yield* gateToolExecution({
294 toolSlug: slug,
295 connectedAccountId: toolkitSlug ? connectedAccounts?.[toolkitSlug] : undefined,
296 connectedAccountWordId: toolkitSlug ? connectedAccountWordIds?.[toolkitSlug] : undefined,
297 snapshot: permissionSnapshot,
298 });
299 const fs = yield* FileSystem.FileSystem;
300 const path = yield* Path.Path;
301 const manifestPath = yield* Effect.orDie(APP_CONFIG.RUN_STAGED_FILES_FILE);
302 const stagedFiles = yield* readRunStagedFiles(fs, manifestPath);
303 const preparedArguments = isMetaToolSlug(slug)
304 ? params.arguments
305 : yield* getOrFetchToolInputDefinition(slug, params.projectScope).pipe(
306 Effect.catch(() => Effect.succeed(null)),
307 Effect.flatMap(definition => {
308 if (!definition) {
309 return Effect.succeed(params.arguments);
310 }
311
312 // A presigned-URL request the API refused is reported as
313 // an upload failure of the source, with the client's error
314 // as its cause.
315 return uploadToolInputFiles({
316 fs,
317 path,
318 toolSlug: slug,
319 toolkitSlug,
320 arguments_: params.arguments,
321 inputSchema: definition.schema,
322 client,
323 stagedFiles,
324 }).pipe(
325 Effect.catchIf(
326 isComposioError,
327 cause =>
328 new ToolFileUploadError({
329 cause,
330 message: cause.message,
331 reason: 'source-read',
332 })
333 )
334 );
335 })
336 );
337
338 return { permissionGateResult, preparedArguments };
339 });
340
341 export const ToolsExecutorLive = Layer.effect(
342 ToolsExecutor,
343 Effect.gen(function* () {
344 // Resolve the client singleton at layer construction time.
345 // The `get` instance method is an Effect.fn that lazily initializes
346 // the Composio client on first call — no environment requirements.
347 const clientSingleton = yield* ComposioClientSingleton;
348
349 // Held rather than required per call: which slugs resolve locally is an
350 // implementation detail of toolkit resolution, not part of what a caller
351 // has to hand the executor.
352 const slugCatalog = yield* ToolkitSlugCatalog;
353 const dashboard = yield* DashboardToolExecution;
354
355 return ToolsExecutor.of({
356 execute: (slug, params) =>
357 Effect.gen(function* () {
358 // Every caller on the execute path hands in a client built for the resolved
359 // org/project; `get()` is unscoped and acts on the key's default project.
360 const resolvedClient = params.client ?? (yield* clientSingleton.get());
361 const sessionContext = yield* resolveToolRouterSessionContext(
362 resolvedClient,
363 params.userId,
364 {
365 manageConnections: true,
366 connectedAccounts: params.connectedAccounts,
367 cacheScope: params.cacheScope,
368 }
369 );
370 const { target } = params;
371 const send =
372 target.kind === 'dashboard'
373 ? createDashboardSend(dashboard, slug, target.orgId, params.connectedAccounts)
374 : yield* createBackendSend(resolvedClient, params.userId, slug, sessionContext);
375 const { permissionGateResult, preparedArguments } = yield* prepareToolExecution(
376 resolvedClient,
377 slug,
378 params,
379 sessionContext
380 );
381
382 const raw = yield* send(preparedArguments);
383
384 return normalizeResponse(raw, permissionGateResult);
385 }).pipe(
386 Effect.catch(error =>
387 toolkitFromToolSlug(slug, toolkitProjectScope(params)).pipe(
388 Effect.flatMap(toolkitSlug => {
389 const mapped = mapComposioError({ error, toolkit: toolkitSlug, toolSlug: slug });
390 return Effect.fail(
391 mapped.normalized instanceof ComposioNoActiveConnectionError
392 ? mapped.normalized
393 : error
394 );
395 })
396 )
397 ),
398 Effect.provideService(ToolkitSlugCatalog, slugCatalog)
399 ),
400 });
401 })
402 );