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
| 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 | ); |