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 945 lines 34.9 KB
Raw
1 import * as BunPath from '@effect/platform-bun/BunPath';
2 import { cliRequestHeaders } from './client-provenance';
3 // This module is preloaded into the user's spawned child process, where no Effect
4 // runtime or @effect/platform layers are provided, so it uses sync Node builtins.
5 // eslint-disable-next-line no-restricted-imports -- sync fs for run-log appends and run-file writes in the child process, outside the Effect runtime
6 import * as fs from 'node:fs';
7 import { ssrfSafeFetch } from '@composio/core/utils/ssrf-guard';
8 import { ChildProcess as Command } from 'effect/process';
9 import * as Path from 'effect/Path';
10 import * as BunServices from '@effect/platform-bun/BunServices';
11 import { Effect, Result, ManagedRuntime, Predicate, Schema } from 'effect';
12 import { z } from 'zod';
13 import { TerminalUI, TerminalUILive } from 'src/services/terminal-ui';
14 import { NodeOs } from 'src/services/node-os';
15 import { collectText } from 'src/services/command-runner';
16 import { debugFlagsToChildEnv } from 'src/services/runtime-flags';
17 import { toolInputRequiredError } from 'src/utils/tool-input-required';
18
19 // One Bun platform runtime shared by every CLI child process this module spawns. ManagedRuntime
20 // builds the layer lazily on first use, so importers that never spawn a child pay nothing, and a
21 // run script that spawns many does not rebuild the platform services per call.
22 const bunCommandRuntime = ManagedRuntime.make(BunServices.layer);
23
24 export type RunHelperContext = {
25 readonly apiKey?: string;
26 readonly baseURL?: string;
27 readonly webURL?: string;
28 readonly orgId?: string;
29 readonly runId?: string;
30 readonly consumerUserId?: string;
31 readonly consumerProjectId?: string;
32 readonly consumerProjectName?: string;
33 readonly perfDebug?: boolean;
34 readonly toolDebug?: boolean;
35 readonly telemetryDebug?: boolean;
36 readonly dryRun?: boolean;
37 readonly skipConnectionCheck?: boolean;
38 readonly skipToolParamsCheck?: boolean;
39 readonly skipChecks?: boolean;
40 readonly debug?: boolean;
41 readonly runOutputDir?: string;
42 readonly runLogFilePath?: string;
43 };
44
45 type RunHelpersInstallParams = {
46 readonly cliPrefix: ReadonlyArray<string>;
47 readonly helperContext?: RunHelperContext;
48 };
49
50 type RunCliResult = unknown;
51
52 type HelperDebugLog = (step: string, details?: Record<string, unknown>) => void;
53
54 const ProxySessionResponse = Schema.Struct({ session_id: Schema.NonEmptyString });
55 const ProxyExecuteCompletedResponse = Schema.Struct({
56 // Absent when an older server answers; any other value fails the decode
57 // instead of being read as a completed call.
58 result_type: Schema.optional(Schema.Literal('completed')),
59 headers: Schema.optional(Schema.Record(Schema.String, Schema.String)),
60 binary_data: Schema.optional(Schema.Struct({ url: Schema.optional(Schema.String) })),
61 data: Schema.optional(Schema.Unknown),
62 status: Schema.optional(Schema.Number),
63 });
64 type ProxyExecuteCompletedResponse = Schema.Schema.Type<typeof ProxyExecuteCompletedResponse>;
65 const ProxyExecuteInputRequiredResponse = Schema.Struct({
66 result_type: Schema.Literal('input_required'),
67 input_requests: Schema.Record(
68 Schema.String,
69 Schema.Struct({
70 type: Schema.Literal('elicitation'),
71 mode: Schema.Literal('form'),
72 message: Schema.String,
73 requested_schema: Schema.Record(Schema.String, Schema.Unknown),
74 })
75 ),
76 request_state: Schema.optional(Schema.String),
77 });
78 const ProxyExecuteResponse = Schema.Union([
79 ProxyExecuteInputRequiredResponse,
80 ProxyExecuteCompletedResponse,
81 ]);
82 const isProxyInputRequired = Schema.is(ProxyExecuteInputRequiredResponse);
83
84 const proxySchema = {
85 type: 'function',
86 description:
87 "Call proxy(toolkit) to get a fetch-compatible function bound to that toolkit's connected account.",
88 parameters: {
89 type: 'object',
90 additionalProperties: false,
91 required: ['toolkit'],
92 properties: {
93 toolkit: {
94 type: 'string',
95 description: 'Toolkit slug whose connected account should be used',
96 },
97 },
98 },
99 returns: {
100 type: 'function',
101 signature: 'fetch(input, init?) => Promise<Response>',
102 requestInit: {
103 type: 'object',
104 additionalProperties: true,
105 properties: {
106 method: { type: 'string', enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] },
107 headers: { description: 'Standard fetch headers init' },
108 body: { description: 'String, JSON-ish value, Blob, ArrayBuffer, or Uint8Array' },
109 },
110 },
111 },
112 };
113
114 const REMOVED_SUB_AGENT_MESSAGE =
115 'experimental_subAgent() was removed from composio run because its agent transport automatically approved permission requests. Print the tool results and let the calling agent summarize them instead.';
116
117 // Rejects instead of throwing synchronously: the removed helper always returned a
118 // promise, so scripts that handle its failure with `.catch` or `Promise.allSettled`
119 // keep doing so.
120 const removedSubAgent = async (): Promise<never> => {
121 throw new Error(REMOVED_SUB_AGENT_MESSAGE);
122 };
123
124 const encodeBase64 = (bytes: Uint8Array): string => {
125 let binary = '';
126 for (const byte of bytes) {
127 binary += String.fromCharCode(byte);
128 }
129 return btoa(binary);
130 };
131
132 // ---------------------------------------------------------------------------
133 // Pure helpers — no run-context captures, hoisted to module scope
134 // ---------------------------------------------------------------------------
135
136 export const parseJson = (text: string): unknown => {
137 const value = text.trim();
138 if (!value) {
139 return undefined;
140 }
141 // Non-JSON output is returned verbatim by design.
142 return Result.getOrElse(
143 Result.try((): unknown => JSON.parse(value)),
144 () => value
145 );
146 };
147
148 // The most specific text a failed proxy response carries: a bare JSON string,
149 // then its `message`, then its `error`, then the raw body.
150 const proxyFailureDetail = (parsed: unknown, raw: string): string | undefined => {
151 if (typeof parsed === 'string') return parsed;
152 if (Predicate.isObject(parsed)) {
153 if (typeof parsed.message === 'string') return parsed.message;
154 if (typeof parsed.error === 'string') return parsed.error;
155 }
156 return raw.trim() || undefined;
157 };
158
159 const executeId = () => crypto.randomUUID().slice(0, 8);
160
161 const truncateDebugText = (value: unknown, max = 240) => {
162 const text = typeof value === 'string' ? value : String(value ?? '');
163 return text.length > max ? `${text.slice(0, max - 1)}…` : text;
164 };
165
166 const previewDebugValue = (value: unknown): string => {
167 if (value == null) return '';
168 if (typeof value === 'string') return truncateDebugText(value.replace(/\s+/g, ' ').trim());
169 if (typeof value === 'number' || typeof value === 'boolean') return String(value);
170 if (Array.isArray(value)) return `array(${value.length})`;
171 if (Predicate.isObject(value)) {
172 const preferred = ['message', 'error', 'title', 'summary', 'brief', 'status'];
173 for (const key of preferred) {
174 const candidate = value[key];
175 if (typeof candidate === 'string' && candidate.trim().length > 0) {
176 return truncateDebugText(candidate.trim());
177 }
178 }
179 return `object{${Object.keys(value).slice(0, 4).join(', ')}}`;
180 }
181 return truncateDebugText(String(value));
182 };
183
184 const formatHelperDebugEvent = (step: string, details: Record<string, unknown> = {}) => {
185 switch (step) {
186 case 'execute.prepare':
187 return `[execute] ${details.slug}`;
188 case 'search.prepare':
189 return `[search] ${truncateDebugText(details.query || '', 96)}`;
190 case 'proxy.request':
191 return `[proxy] ${details.method} ${truncateDebugText(details.endpoint || '', 96)}`;
192 case 'cli.result': {
193 const command = typeof details.command === 'string' ? details.command : 'cli';
194 const state = details.successful === false ? 'failed' : 'ok';
195 const preview = previewDebugValue(details.preview);
196 return `[${command}] ${state}${preview ? ` ${preview}` : ''}`;
197 }
198 case 'cli.error': {
199 const command = typeof details.command === 'string' ? details.command : 'cli';
200 const stderr = previewDebugValue(details.stderr);
201 return `[${command}] failed${stderr ? ` ${stderr}` : ''}`;
202 }
203 default:
204 return null;
205 }
206 };
207
208 const stringifyForPrompt = (value: unknown): string => {
209 if (value === undefined) return 'undefined';
210 if (value === null) return 'null';
211 if (typeof value === 'string') return value;
212 if (typeof value === 'number' || typeof value === 'boolean' || typeof value === 'bigint') {
213 return String(value);
214 }
215 return Result.getOrElse(
216 Result.try(() => JSON.stringify(value, null, 2)),
217 () => String(value)
218 );
219 };
220
221 const attachPromptMethod = <T>(value: T): T => {
222 if (!Predicate.isObject(value)) return value;
223 if (typeof value.prompt === 'function') return value;
224 Object.defineProperty(value, 'prompt', {
225 value: () => stringifyForPrompt('data' in value ? value.data : value),
226 enumerable: false,
227 });
228 return value;
229 };
230
231 const isPlainObjectForExecute = Predicate.isObject;
232
233 // The extension of the name a nameless Blob is uploaded under. Cosmetic: the Blob's
234 // type reaches the upload through `COMPOSIO_RUN_STAGED_FILES_FILE`, not through this
235 // extension. A subtype that is not a plain token (`vnd.openxmlformats-…`) is `bin`.
236 const runFileExtensionFromMimeType = (mimeType: string): string => {
237 const normalized = mimeType.split(';')[0]?.trim().toLowerCase() ?? '';
238 const explicit: Record<string, string> = {
239 'text/plain': 'txt',
240 'image/jpeg': 'jpg',
241 };
242 if (Object.hasOwn(explicit, normalized)) return explicit[normalized];
243 const subtype = normalized.split('/')[1]?.split('+').pop() ?? '';
244 return /^[a-z0-9]{1,10}$/.test(subtype) ? subtype : 'bin';
245 };
246
247 const describeDebugValue = (value: unknown) => {
248 if (Array.isArray(value)) return { type: 'array', length: value.length };
249 if (Predicate.isObject(value)) {
250 return { type: 'object', keys: Object.keys(value).slice(0, 20) };
251 }
252 return {
253 type: typeof value,
254 value: typeof value === 'string' ? value.slice(0, 200) : (value ?? null),
255 };
256 };
257
258 const summarizeCliResultPreview = (result: RunCliResult): unknown => {
259 if (!Predicate.isObject(result)) return result;
260 if ('data' in result && result.data !== undefined) return result.data;
261 if (typeof result.error === 'string' && result.error.trim().length > 0)
262 return result.error.trim();
263 return result;
264 };
265
266 const normalizeProxyToolkit = (toolkit: string) => {
267 if (typeof toolkit !== 'string' || toolkit.trim().length === 0) {
268 throw new Error('proxy() requires a non-empty toolkit string.');
269 }
270 return toolkit.trim();
271 };
272
273 const normalizeFetchHeaders = (headers: HeadersInit | undefined) => {
274 if (!headers) return [];
275 const normalized: Array<{ name: string; type: string; value: string }> = [];
276 new Headers(headers).forEach((value, name) => {
277 normalized.push({ name, type: 'header', value });
278 });
279 return normalized;
280 };
281
282 const normalizeFetchBody = async (body: unknown) => {
283 if (body === undefined || body === null) return undefined;
284 if (typeof body === 'string' || typeof body === 'number' || typeof body === 'boolean')
285 return body;
286 if (typeof Blob !== 'undefined' && body instanceof Blob) return await body.text();
287 if (body instanceof ArrayBuffer) return encodeBase64(new Uint8Array(body));
288 if (ArrayBuffer.isView(body)) {
289 return encodeBase64(new Uint8Array(body.buffer, body.byteOffset, body.byteLength));
290 }
291 return body;
292 };
293
294 const normalizeFetchInput = async (input: unknown, init: RequestInit = {}) => {
295 if (typeof Request !== 'undefined' && input instanceof Request) {
296 throw new Error(
297 'proxy() does not support passing a Request instance yet. Pass a URL string and init instead.'
298 );
299 }
300 const endpoint = input instanceof URL ? input.toString() : input;
301 if (typeof endpoint !== 'string' || endpoint.trim().length === 0) {
302 throw new Error('proxy fetch requires a non-empty URL string or URL object.');
303 }
304 const method = typeof init.method === 'string' ? init.method.toUpperCase() : 'GET';
305 if (!['GET', 'POST', 'PUT', 'DELETE', 'PATCH'].includes(method)) {
306 throw new Error('proxy fetch only supports GET, POST, PUT, DELETE, PATCH.');
307 }
308 return {
309 endpoint: endpoint.trim(),
310 method,
311 parameters: normalizeFetchHeaders(init.headers),
312 body: await normalizeFetchBody(init.body),
313 };
314 };
315
316 const toProxyResponse = async (result: ProxyExecuteCompletedResponse) => {
317 const headers = new Headers(result?.headers || {});
318 if (result?.binary_data?.url) {
319 const binaryResponse = await ssrfSafeFetch(
320 result.binary_data.url,
321 {},
322 {
323 requirePinnedConnection: true,
324 }
325 );
326 binaryResponse.headers.forEach((value, key) => {
327 if (!headers.has(key)) headers.set(key, value);
328 });
329 return new Response(binaryResponse.body, {
330 status: result.status ?? binaryResponse.status,
331 headers,
332 });
333 }
334 if (result?.data === undefined || result?.data === null) {
335 return new Response(null, { status: result?.status ?? 200, headers });
336 }
337 if (typeof result.data === 'string') {
338 if (!headers.has('content-type')) headers.set('content-type', 'text/plain; charset=utf-8');
339 return new Response(result.data, { status: result.status ?? 200, headers });
340 }
341 if (!headers.has('content-type')) headers.set('content-type', 'application/json; charset=utf-8');
342 return new Response(JSON.stringify(result.data), { status: result.status ?? 200, headers });
343 };
344
345 // ---------------------------------------------------------------------------
346 // Helper factories — capture the per-run context passed by installRunHelpers
347 // ---------------------------------------------------------------------------
348
349 type RunHelperLoggers = {
350 readonly perfDebugLog: (phase: string, label: string, details?: Record<string, unknown>) => void;
351 readonly helperDebugLog: HelperDebugLog;
352 };
353
354 const createRunHelperLoggers = (params: {
355 readonly helperContext: RunHelperContext;
356 readonly writeError: (line: string) => void;
357 readonly sharedRunLogFilePath: string | null;
358 readonly perfDebugEnabled: boolean;
359 readonly perfDebugStart: number;
360 }): RunHelperLoggers => {
361 const { helperContext, writeError, sharedRunLogFilePath, perfDebugEnabled, perfDebugStart } =
362 params;
363
364 const appendRunLogLine = (line: string) => {
365 if (!sharedRunLogFilePath || line.length === 0) return;
366 fs.appendFileSync(sharedRunLogFilePath, `${line}\n`, 'utf8');
367 };
368
369 const perfDebugLog = (phase: string, label: string, details: Record<string, unknown> = {}) => {
370 if (!perfDebugEnabled) return;
371 const elapsedMs = Date.now() - perfDebugStart;
372 const payload = { phase, label, elapsedMs, ...details };
373 writeError(`[perf] ${JSON.stringify(payload)}`);
374 };
375
376 const helperDebugLog: HelperDebugLog = (step, details = {}) => {
377 const formattedLine = formatHelperDebugEvent(step, details);
378 const elapsedMs = Date.now() - perfDebugStart;
379 const line = formattedLine ?? `[run:debug] ${JSON.stringify({ step, elapsedMs, ...details })}`;
380 appendRunLogLine(line);
381 if (helperContext.debug === true) {
382 writeError(line);
383 }
384 };
385
386 return { perfDebugLog, helperDebugLog };
387 };
388
389 /**
390 * An `execute()` payload with every File and Blob written to disk: the spawned
391 * `composio execute` takes `--data` JSON, so each one becomes its staged path.
392 */
393 /** What the upload reports for a staged file, in place of its staged path's. */
394 type StagedFileLabel = { readonly name: string; readonly mimetype?: string };
395
396 /**
397 * An `execute()` payload with every File and Blob written to disk: the spawned
398 * `composio execute` takes `--data` JSON, so each one becomes its staged path.
399 */
400 type MaterializedExecutePayload = {
401 readonly payload: unknown;
402 /**
403 * Staged path -> the File or Blob's own name and `type`. A path carries
404 * neither, so the child receives these through `COMPOSIO_RUN_STAGED_FILES_FILE`
405 * and uploads the file under them.
406 */
407 readonly stagedFiles: ReadonlyArray<readonly [string, StagedFileLabel]>;
408 };
409
410 const createExecutePayloadMaterializer = (params: {
411 readonly path: Path.Path;
412 readonly tmpdir: string;
413 readonly sharedRunOutputDir: string | null;
414 }): ((value: unknown) => Promise<MaterializedExecutePayload>) => {
415 const { path, tmpdir, sharedRunOutputDir } = params;
416
417 // The name the upload sends: a File's own, without any directory part.
418 const uploadName = (blob: Blob): string => {
419 const baseName = blob instanceof File ? path.basename(blob.name).trim() : '';
420 return baseName.length > 0 && baseName !== '.' && baseName !== '..'
421 ? baseName
422 : `file-${executeId()}.${runFileExtensionFromMimeType(blob.type)}`;
423 };
424
425 const writeTempExecuteFile = async (
426 blob: Blob,
427 stagedFiles: Array<readonly [string, StagedFileLabel]>
428 ): Promise<string> => {
429 const outputDir = sharedRunOutputDir || path.join(tmpdir, 'composio-run-files');
430 fs.mkdirSync(outputDir, { recursive: true });
431 const name = uploadName(blob);
432 // Staged under a generated name, never the File's own: the child still runs
433 // the sensitive-path denylist on this path, and a script-created
434 // `.env.example` or `id_rsa` is not a file of the user's to protect. The
435 // extension is kept only as a fallback for the type.
436 const extension = path.extname(name);
437 const filePath = path.join(
438 outputDir,
439 `file-${executeId()}${/^\.[A-Za-z0-9]{1,10}$/.test(extension) ? extension : ''}`
440 );
441 fs.writeFileSync(filePath, new Uint8Array(await blob.arrayBuffer()));
442 const mimetype = blob.type.trim();
443 stagedFiles.push([filePath, mimetype.length > 0 ? { name, mimetype } : { name }]);
444 return filePath;
445 };
446
447 const materialize = async (
448 value: unknown,
449 stagedFiles: Array<readonly [string, StagedFileLabel]>
450 ): Promise<unknown> => {
451 if (typeof Blob !== 'undefined' && value instanceof Blob) {
452 return writeTempExecuteFile(value, stagedFiles);
453 }
454 if (Array.isArray(value)) {
455 return Promise.all(value.map(item => materialize(item, stagedFiles)));
456 }
457 if (isPlainObjectForExecute(value)) {
458 const entries = await Promise.all(
459 Object.entries(value).map(async ([key, entryValue]) => [
460 key,
461 await materialize(entryValue, stagedFiles),
462 ])
463 );
464 return Object.fromEntries(entries);
465 }
466 return value;
467 };
468
469 return async value => {
470 const stagedFiles: Array<readonly [string, StagedFileLabel]> = [];
471 const payload = await materialize(value, stagedFiles);
472 return { payload, stagedFiles };
473 };
474 };
475
476 const isReportedFailure = (result: RunCliResult): boolean =>
477 Predicate.isObject(result) && result.successful === false;
478
479 type RunCliJson = (
480 args: ReadonlyArray<string>,
481 extraEnv?: Readonly<Record<string, string>>
482 ) => Promise<RunCliResult>;
483
484 const createCliRunner = (params: {
485 readonly cliPrefix: ReadonlyArray<string>;
486 readonly helperContext: RunHelperContext;
487 readonly sharedRunOutputDir: string | null;
488 readonly perfDebugEnabled: boolean;
489 readonly toolDebugEnabled: boolean;
490 readonly loggers: RunHelperLoggers;
491 }): RunCliJson => {
492 const { cliPrefix, helperContext, sharedRunOutputDir, perfDebugEnabled, toolDebugEnabled } =
493 params;
494 const { perfDebugLog, helperDebugLog } = params.loggers;
495 let perfDebugSeq = 0;
496
497 const maybeLoadStoredCliResult = (result: RunCliResult): RunCliResult => {
498 if (!Predicate.isObject(result) || result.storedInFile !== true) {
499 return attachPromptMethod(result);
500 }
501 helperDebugLog('cli.result.stored_in_file', {
502 outputFilePath: result.outputFilePath ?? null,
503 tokenCount: result.tokenCount ?? null,
504 });
505 const outputFilePath = typeof result.outputFilePath === 'string' ? result.outputFilePath : null;
506 return attachPromptMethod({
507 ...result,
508 data: {
509 storedInFilePath: outputFilePath !== null,
510 outputFilePath,
511 },
512 });
513 };
514
515 const logCliResultPreview = (
516 requestId: string,
517 command: string | undefined,
518 result: RunCliResult
519 ) => {
520 if (!Predicate.isObject(result)) {
521 helperDebugLog('cli.result', {
522 requestId,
523 command,
524 preview: result,
525 result: describeDebugValue(result),
526 });
527 return;
528 }
529 helperDebugLog('cli.result', {
530 requestId,
531 command,
532 successful: result.successful ?? null,
533 storedInFile: result.storedInFile ?? false,
534 outputFilePath: result.outputFilePath ?? null,
535 error: result.error ?? null,
536 topLevelKeys: Object.keys(result).slice(0, 20),
537 data: 'data' in result ? describeDebugValue(result.data) : null,
538 preview: summarizeCliResultPreview(result),
539 });
540 };
541
542 // Invariant for the life of the run session, so built once rather than per
543 // spawned CLI call.
544 const env: Record<string, string> = {
545 // The platform command inherits the ambient environment by default. An
546 // empty BUN_BE_BUN masks the parent run process's Bun compatibility flag
547 // without copying or enumerating unrelated values.
548 BUN_BE_BUN: '',
549 ...(helperContext.apiKey ? { COMPOSIO_USER_API_KEY: helperContext.apiKey } : {}),
550 ...(helperContext.baseURL ? { COMPOSIO_BASE_URL: helperContext.baseURL } : {}),
551 ...(helperContext.webURL ? { COMPOSIO_WEB_URL: helperContext.webURL } : {}),
552 COMPOSIO_CLI_INVOCATION_ORIGIN: 'run',
553 ...(helperContext.runId ? { COMPOSIO_CLI_PARENT_RUN_ID: helperContext.runId } : {}),
554 ...(sharedRunOutputDir ? { COMPOSIO_RUN_OUTPUT_DIR: sharedRunOutputDir } : {}),
555 ...debugFlagsToChildEnv({
556 perfDebug: perfDebugEnabled,
557 toolDebug: toolDebugEnabled,
558 telemetryDebug: helperContext.telemetryDebug === true,
559 }),
560 };
561
562 const runCliJson = async (
563 args: ReadonlyArray<string>,
564 extraEnv: Readonly<Record<string, string>> = {}
565 ): Promise<RunCliResult> => {
566 const requestId = `${args[0] ?? 'cli'}#${++perfDebugSeq}`;
567 helperDebugLog('cli.start', { requestId, args });
568 perfDebugLog('start', requestId, { cmd: args });
569 const [executable, ...commandArgs] = [...cliPrefix, ...args];
570 const inheritStderr = perfDebugEnabled || toolDebugEnabled;
571 const { exitCode, stderr, stdout } = await bunCommandRuntime.runPromise(
572 Effect.scoped(
573 Effect.gen(function* () {
574 const child = yield* Command.make(executable, commandArgs, {
575 env: { ...env, ...extraEnv },
576 extendEnv: true,
577 stdin: 'inherit',
578 stderr: inheritStderr ? 'inherit' : 'pipe',
579 });
580 const [childExitCode, childStdout, childStderr] = yield* Effect.all(
581 [
582 child.exitCode,
583 collectText(child.stdout),
584 inheritStderr ? Effect.succeed('') : collectText(child.stderr),
585 ],
586 { concurrency: 'unbounded' }
587 );
588 return {
589 exitCode: Number(childExitCode),
590 stdout: childStdout,
591 stderr: childStderr,
592 };
593 })
594 )
595 );
596 const result = maybeLoadStoredCliResult(parseJson(stdout));
597 // A failed execution exits 1 with its `successful: false` result on stdout. That result is
598 // the answer, so it goes back to the caller (`execute()` throws its error message) instead
599 // of a generic exit-code error.
600 if (exitCode !== 0 && !isReportedFailure(result)) {
601 perfDebugLog('error', requestId, { exitCode, stderr: stderr.trim() || undefined });
602 helperDebugLog('cli.error', {
603 requestId,
604 command: args[0],
605 exitCode,
606 stderr: stderr.trim() || undefined,
607 });
608 const error = new Error(`composio ${args.join(' ')} failed with exit code ${exitCode}`);
609 Object.assign(error, { exitCode, result, stderr: stderr.trim() || undefined });
610 throw error;
611 }
612 if (result === undefined) {
613 const details = stderr.trim();
614 const suffix = details ? `: ${details}` : '';
615 perfDebugLog('error', requestId, { exitCode, stderr: details || undefined, noJson: true });
616 helperDebugLog('cli.error', {
617 requestId,
618 command: args[0],
619 exitCode,
620 stderr: details || undefined,
621 noJson: true,
622 });
623 const error = new Error(`composio ${args.join(' ')} returned no JSON output${suffix}`);
624 Object.assign(error, { exitCode, result, stderr: details || undefined });
625 throw error;
626 }
627 perfDebugLog('end', requestId, {
628 exitCode,
629 stdoutBytes: stdout.length,
630 stderrBytes: stderr.length,
631 });
632 logCliResultPreview(requestId, args[0], result);
633 helperDebugLog('cli.done', { requestId, exitCode });
634 return result;
635 };
636
637 return runCliJson;
638 };
639
640 const createSearchAndExecuteHelpers = (params: {
641 readonly helperContext: RunHelperContext;
642 readonly sharedRunOutputDir: string | null;
643 readonly path: Path.Path;
644 readonly tmpdir: string;
645 readonly runCliJson: RunCliJson;
646 readonly materializeExecutePayload: (value: unknown) => Promise<MaterializedExecutePayload>;
647 readonly helperDebugLog: HelperDebugLog;
648 }) => {
649 const {
650 helperContext,
651 sharedRunOutputDir,
652 path,
653 tmpdir,
654 runCliJson,
655 materializeExecutePayload,
656 helperDebugLog,
657 } = params;
658
659 const search = async (
660 query: string,
661 options: Record<string, unknown> = {}
662 ): Promise<RunCliResult> => {
663 helperDebugLog('search.prepare', { query, options });
664 const args = ['search', query];
665 if (Array.isArray(options.toolkits) && options.toolkits.length > 0) {
666 args.push('--toolkits', options.toolkits.join(','));
667 } else if (typeof options.toolkits === 'string' && options.toolkits.trim().length > 0) {
668 args.push('--toolkits', options.toolkits);
669 }
670 if (typeof options.limit === 'number') {
671 args.push('--limit', String(options.limit));
672 }
673 return runCliJson(args);
674 };
675
676 const execute = async (
677 slug: string,
678 data: unknown = {},
679 options: { account?: string } = {}
680 ): Promise<RunCliResult> => {
681 helperDebugLog('execute.prepare', {
682 slug,
683 hasData: data !== undefined,
684 account: options.account ?? null,
685 });
686 const args = ['execute', slug];
687 if (helperContext.dryRun === true) args.push('--dry-run');
688 if (helperContext.skipConnectionCheck === true) args.push('--skip-connection-check');
689 if (helperContext.skipToolParamsCheck === true) args.push('--skip-tool-params-check');
690 if (helperContext.skipChecks === true) args.push('--skip-checks');
691 if (typeof options.account === 'string' && options.account.trim().length > 0) {
692 args.push('--account', options.account.trim());
693 }
694 // Always set, so a value this process inherited never reaches the child.
695 let stagedFiles: MaterializedExecutePayload['stagedFiles'] = [];
696 if (data !== undefined) {
697 const materialized = await materializeExecutePayload(data);
698 const preparedData = materialized.payload;
699 stagedFiles = materialized.stagedFiles;
700 const serialized =
701 typeof preparedData === 'string' ? preparedData : JSON.stringify(preparedData);
702 if (sharedRunOutputDir) {
703 const tmpFile = `${sharedRunOutputDir}/execute-data-${slug}-${executeId()}.json`;
704 fs.writeFileSync(tmpFile, serialized, 'utf8');
705 args.push('--data', `@${tmpFile}`);
706 } else {
707 args.push('--data', serialized);
708 }
709 }
710 const metadataDirectory =
711 stagedFiles.length > 0
712 ? fs.mkdtempSync(path.join(tmpdir, 'composio-run-staged-'))
713 : undefined;
714 const metadataFile = metadataDirectory ? path.join(metadataDirectory, 'files.json') : '';
715 const runWithStagedFiles = async (): Promise<RunCliResult> => {
716 if (metadataFile) {
717 fs.writeFileSync(metadataFile, JSON.stringify(Object.fromEntries(stagedFiles)), {
718 encoding: 'utf8',
719 mode: 0o600,
720 });
721 }
722 const result = await runCliJson(args, {
723 COMPOSIO_RUN_STAGED_FILES_FILE: metadataFile,
724 });
725 if (Predicate.isObject(result) && result.successful === false) {
726 const message =
727 typeof result.error === 'string' && result.error.trim().length > 0
728 ? result.error.trim()
729 : `composio execute ${slug} failed`;
730 const error = new Error(message);
731 Object.assign(error, { result, slug });
732 throw error;
733 }
734 return result;
735 };
736 return runWithStagedFiles().finally(() => {
737 if (metadataDirectory) fs.rmSync(metadataDirectory, { recursive: true, force: true });
738 });
739 };
740
741 return { search, execute };
742 };
743
744 const createProxyHelper = (params: {
745 readonly helperContext: RunHelperContext;
746 readonly composioBaseURL: string;
747 readonly helperDebugLog: HelperDebugLog;
748 }) => {
749 const { helperContext, composioBaseURL, helperDebugLog } = params;
750 const proxySessionCache = new Map<string, string>();
751
752 const requireConsumerProxyContext = () => {
753 if (!helperContext.apiKey) {
754 throw new Error('proxy() requires an authenticated Composio user session.');
755 }
756 if (!helperContext.orgId || !helperContext.consumerProjectId || !helperContext.consumerUserId) {
757 throw new Error(
758 'proxy() requires a consumer project context so it can use the consumer project credentials.'
759 );
760 }
761 return {
762 apiKey: helperContext.apiKey,
763 orgId: helperContext.orgId,
764 projectId: helperContext.consumerProjectId,
765 userId: helperContext.consumerUserId,
766 };
767 };
768
769 const fetchComposioJson = async (pathname: string, body: Record<string, unknown>) => {
770 const auth = requireConsumerProxyContext();
771 const response = await fetch(`${composioBaseURL}${pathname}`, {
772 method: 'POST',
773 headers: {
774 ...cliRequestHeaders(),
775 'content-type': 'application/json',
776 'x-user-api-key': auth.apiKey,
777 'x-org-id': auth.orgId,
778 'x-project-id': auth.projectId,
779 },
780 body: JSON.stringify(body),
781 });
782 const raw = await response.text();
783 const parsed = parseJson(raw);
784 if (!response.ok) {
785 const detail = proxyFailureDetail(parsed, raw);
786 const error = new Error(
787 `Composio proxy request failed with status ${response.status}${detail ? `: ${detail}` : ''}`
788 );
789 Object.assign(error, { status: response.status, response: parsed ?? raw });
790 throw error;
791 }
792 return parsed;
793 };
794
795 const getProxySessionId = async (toolkit: string) => {
796 const cached = proxySessionCache.get(toolkit);
797 if (cached) return cached;
798 const auth = requireConsumerProxyContext();
799 const created = await Schema.decodeUnknownPromise(ProxySessionResponse)(
800 await fetchComposioJson('/api/v3/tool_router/session', {
801 user_id: auth.userId,
802 manage_connections: { enable: false },
803 toolkits: { enable: [toolkit] },
804 })
805 );
806 const sessionId = created.session_id;
807 proxySessionCache.set(toolkit, sessionId);
808 return sessionId;
809 };
810
811 const proxy = async (toolkit: string) => {
812 const normalizedToolkit = normalizeProxyToolkit(toolkit);
813 helperDebugLog('proxy.session', {
814 toolkit: normalizedToolkit,
815 cached: proxySessionCache.has(normalizedToolkit),
816 });
817 const sessionId = await getProxySessionId(normalizedToolkit);
818 const proxyFetch = async (input: string | URL, init: RequestInit = {}) => {
819 const request = await normalizeFetchInput(input, init);
820 helperDebugLog('proxy.request', {
821 toolkit: normalizedToolkit,
822 method: request.method,
823 endpoint: request.endpoint,
824 });
825 const result = await Schema.decodeUnknownPromise(ProxyExecuteResponse)(
826 await fetchComposioJson(`/api/v3/tool_router/session/${sessionId}/proxy_execute`, {
827 toolkit_slug: normalizedToolkit,
828 endpoint: request.endpoint,
829 method: request.method,
830 ...(request.body !== undefined ? { body: request.body } : {}),
831 ...(request.parameters.length > 0
832 ? {
833 parameters: request.parameters.map(parameter => ({
834 name: parameter.name,
835 type: parameter.type,
836 value: String(parameter.value),
837 })),
838 }
839 : {}),
840 })
841 );
842 // An approval request is not a response from the proxied API: converting
843 // it would hand the script an empty 200 for a call that never ran.
844 if (isProxyInputRequired(result)) {
845 // The error is thrown into the user's script, where it is likely to be
846 // logged whole. `request_state` is continuation state the CLI cannot
847 // use yet, so it is left off the error.
848 throw toolInputRequiredError(`${request.method} proxy call via "${normalizedToolkit}"`, {
849 input_requests: result.input_requests,
850 });
851 }
852 return toProxyResponse(result);
853 };
854 Object.defineProperty(proxyFetch, 'toolkit', { value: normalizedToolkit });
855 return proxyFetch;
856 };
857
858 Object.defineProperty(proxy, 'schema', { value: proxySchema });
859 return proxy;
860 };
861
862 export const installRunHelpers = async ({
863 cliPrefix,
864 helperContext = {},
865 }: RunHelpersInstallParams): Promise<void> => {
866 // This preload runs in the user's child process, outside the CLI runtime.
867 // Resolve the live services once at that boundary and keep all writes centralized.
868 const terminal = Effect.runSync(TerminalUI.pipe(Effect.provide(TerminalUILive)));
869 const path = Effect.runSync(Path.Path.pipe(Effect.provide(BunPath.layer)));
870 const nodeOs = Effect.runSync(NodeOs.pipe(Effect.provide(NodeOs.Default)));
871 const writeError = (line: string) => Effect.runSync(terminal.error(line));
872
873 Reflect.set(globalThis, 'z', z);
874 Reflect.set(globalThis, 'zod', z);
875
876 const perfDebugEnabled = helperContext.perfDebug === true;
877 const toolDebugEnabled = helperContext.toolDebug === true;
878 const perfDebugStart = Date.now();
879 const composioBaseURL = (helperContext.baseURL || 'https://backend.composio.dev').replace(
880 /\/$/,
881 ''
882 );
883 const sharedRunOutputDir =
884 typeof helperContext.runOutputDir === 'string' && helperContext.runOutputDir.length > 0
885 ? helperContext.runOutputDir
886 : null;
887 const sharedRunLogFilePath =
888 typeof helperContext.runLogFilePath === 'string' && helperContext.runLogFilePath.length > 0
889 ? helperContext.runLogFilePath
890 : null;
891
892 const loggers = createRunHelperLoggers({
893 helperContext,
894 writeError,
895 sharedRunLogFilePath,
896 perfDebugEnabled,
897 perfDebugStart,
898 });
899 const { helperDebugLog } = loggers;
900
901 const materializeExecutePayload = createExecutePayloadMaterializer({
902 path,
903 tmpdir: nodeOs.tmpdir,
904 sharedRunOutputDir,
905 });
906 const runCliJson = createCliRunner({
907 cliPrefix,
908 helperContext,
909 sharedRunOutputDir,
910 perfDebugEnabled,
911 toolDebugEnabled,
912 loggers,
913 });
914 const { search, execute } = createSearchAndExecuteHelpers({
915 helperContext,
916 sharedRunOutputDir,
917 path,
918 tmpdir: nodeOs.tmpdir,
919 runCliJson,
920 materializeExecutePayload,
921 helperDebugLog,
922 });
923
924 Reflect.set(globalThis, 'experimental_subAgent', removedSubAgent);
925 Reflect.set(globalThis, 'invokeAgent', removedSubAgent);
926
927 const proxy = createProxyHelper({ helperContext, composioBaseURL, helperDebugLog });
928
929 Reflect.set(globalThis, 'search', search);
930 Reflect.set(globalThis, 'execute', execute);
931 Reflect.set(globalThis, 'proxy', proxy);
932
933 Object.defineProperty(globalThis, '__composioRunContext', {
934 value: Object.freeze({
935 outputDir: sharedRunOutputDir,
936 logFilePath: sharedRunLogFilePath,
937 }),
938 configurable: true,
939 });
940
941 Object.defineProperty(globalThis, '__composioConsumerContext', {
942 value: helperContext,
943 configurable: true,
944 });
945 };