1
import { cliAnalyticsProvenance } from 'src/services/client-provenance';
2
-import type { CliCommandTelemetryContext, TrackEvent } from './types';
2
+import { Option, Schema } from 'effect';
3
+import { CliError } from 'effect/cli';
4
+import type { CliCommandTelemetryContext, TelemetryFamily, TrackEvent } from './types';
5
+import { type CommandIdentity, commandPathOf } from 'src/invocation/command-identity';
6
import { APP_VERSION } from 'src/constants';
7
import { inferSkillReleaseChannel } from 'src/effects/install-skill';
8
import type { AgentHost } from 'src/services/agent-host';
11
import { SetupCommandError } from 'src/services/setup-command-error';
12
import { ToolInputValidationError } from 'src/services/tool-input-validation';
13
import { guessToolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
11
-import { rootCommandIndex } from 'src/utils/cli-args';
14
15
export const CLI_ANALYTICS_EVENTS = {
16
CLI_COMMAND_INVOKED: 'CLI_COMMAND_INVOKED',
153
},
154
});
155
154
-const KNOWN_COMMAND_TOKENS = new Set([
155
- 'version',
156
- 'upgrade',
157
- 'whoami',
158
- 'login',
159
- 'logout',
160
- 'run',
161
- 'install',
162
- 'setup',
163
- 'dev',
164
- 'generate',
165
- 'tools',
166
- 'toolkits',
167
- 'toolkit',
168
- 'search',
169
- 'execute',
170
- 'playground-execute',
171
- 'link',
172
- 'proxy',
173
- 'artifacts',
174
- 'cwd',
175
- 'connected-accounts',
176
- 'auth-configs',
177
- 'triggers',
178
- 'logs',
179
- 'orgs',
180
- 'projects',
181
- 'info',
182
- 'list',
183
- 'create',
184
- 'delete',
185
- 'enable',
186
- 'disable',
187
- 'status',
188
- 'listen',
189
- 'switch',
190
- 'py',
191
- 'ts',
192
-]);
193
-
156
const TOOL_NOT_FOUND_PATTERN = /\btool\b.*\bnot found\b/i;
157
const TOOL_VALIDATION_PATTERN = /\b(?:validation|invalid parameter|invalid argument)\b/i;
158
const TOOL_NOT_FOUND_CODES: ReadonlySet<number> = new Set([
171
3702, // ComposioTools_ValidationError
172
]);
173
212
-const extractCommandPath = (argv: ReadonlyArray<string>): string => {
213
- const commandTokens: string[] = [];
214
- const args = argv.slice(2);
215
- for (const token of args.slice(rootCommandIndex(args))) {
216
- if (!token || token.startsWith('-') || !KNOWN_COMMAND_TOKENS.has(token)) {
217
- break;
218
- }
219
- commandTokens.push(token);
220
- }
221
-
222
- return commandTokens.length > 0 ? commandTokens.join(' ') : 'composio';
223
-};
224
-
174
const extractFlagNames = (argv: ReadonlyArray<string>): ReadonlyArray<string> =>
175
[
176
...new Set(
211
error instanceof Error && error.name ? error.name : 'UnknownError';
212
213
const failureReasonProperties = (error: unknown) => {
214
+ // `effect/cli` rejected argv: no command ran, and the event's command path is the one the
215
+ // parser reached (`CliError.ShowHelp.commandPath`). A bare group's help carries no errors.
216
+ if (error instanceof CliError.ShowHelp && error.errors.length > 0) {
217
+ return { failure_reason_code: 'parse_error' };
218
+ }
219
if (error instanceof SetupCommandError) return { failure_reason_code: error.reasonCode };
220
if (error instanceof ChildProcessExited || error instanceof ChildProcessSignaled) {
221
return { failure_reason_code: 'child_exit' };
248
return undefined;
249
};
250
297
-const getTrailingPositionals = (context: CliCommandTelemetryContext): ReadonlyArray<string> => {
298
- const commandTokenCount =
299
- context.commandPath === 'composio' ? 0 : context.commandPath.split(' ').length;
300
- const rootArgs = context.argv.slice(2);
301
- const args = rootArgs.slice(rootCommandIndex(rootArgs) + commandTokenCount);
302
- const positionals: string[] = [];
303
-
304
- for (let index = 0; index < args.length; index += 1) {
305
- const token = args[index];
306
- if (!token) continue;
307
-
308
- if (token === '--') {
309
- break;
310
- }
311
-
312
- if (token.startsWith('-')) {
313
- const expectsValue = [
314
- '--data',
315
- '-d',
316
- '--toolkits',
317
- '--limit',
318
- '--user-id',
319
- '--project-name',
320
- '--auth-config',
321
- '--file',
322
- '-f',
323
- ].includes(token);
324
- if (expectsValue) {
325
- index += 1;
326
- }
327
- continue;
328
- }
329
-
330
- positionals.push(token);
331
- }
332
-
333
- return positionals;
334
-};
335
-
251
const getExecuteCommandProperties = (context: CliCommandTelemetryContext) => {
337
- const slug = getTrailingPositionals(context)[0];
252
+ const slug = context.argument;
253
return {
254
source: 'cli',
255
invocation_origin: context.invocationOrigin,
275
276
// Search queries are user-authored free text, so only their shape is recorded.
277
const getSearchCommandProperties = (context: CliCommandTelemetryContext) => {
363
- const query = getTrailingPositionals(context)[0] ?? '';
278
+ const query = context.argument ?? '';
279
return {
280
source: 'cli',
281
invocation_origin: context.invocationOrigin,
292
};
293
294
const getLinkCommandProperties = (context: CliCommandTelemetryContext) => {
380
- const firstPositional = getTrailingPositionals(context)[0];
295
return {
296
source: 'cli',
297
invocation_origin: context.invocationOrigin,
300
cli_version: context.cliVersion,
301
command_path: context.commandPath,
302
duration_ms: Date.now() - context.startedAt,
389
- toolkit: getFlagValue(context.argv, '--toolkit') ?? firstPositional,
303
+ toolkit: context.argument,
304
no_browser: isFlagPresent(context.argv, '--no-browser'),
305
no_wait: isFlagPresent(context.argv, '--no-wait'),
306
has_auth_config: isFlagPresent(context.argv, '--auth-config'),
372
cli_version: context.cliVersion,
373
command_path: context.commandPath,
374
duration_ms: Date.now() - context.startedAt,
461
- has_endpoint: typeof getTrailingPositionals(context)[0] === 'string',
375
+ has_endpoint: typeof context.argument === 'string',
376
toolkit: getFlagValue(context.argv, '--toolkit', '-t'),
377
method: getFlagValue(context.argv, '--method', '-X') ?? 'GET',
378
has_data: isFlagPresent(context.argv, '--data', '-d'),
381
skip_connection_check: isFlagPresent(context.argv, '--skip-connection-check'),
382
});
383
470
-const isExecuteCommand = (commandPath: string): boolean =>
471
- commandPath === 'execute' || commandPath === 'dev playground-execute';
472
-
473
-const isSearchCommand = (commandPath: string): boolean =>
474
- commandPath === 'search' || commandPath === 'dev toolkits search';
475
-
476
-const isLinkCommand = (commandPath: string): boolean =>
477
- commandPath === 'link' || commandPath === 'dev connected-accounts link';
478
-
479
-const isLoginCommand = (commandPath: string): boolean => commandPath === 'login';
480
-
481
-const isLogoutCommand = (commandPath: string): boolean => commandPath === 'logout';
482
-
483
-const isProxyCommand = (commandPath: string): boolean => commandPath === 'proxy';
484
-
485
-const isRunCommand = (commandPath: string): boolean => commandPath === 'run';
486
-
487
-const isInstallCommand = (commandPath: string): boolean => commandPath === 'install';
488
-
489
-const isSetupCommand = (commandPath: string): boolean => commandPath === 'setup';
490
-
491
-const isGenericOnlyCommand = (commandPath: string): boolean =>
492
- commandPath === 'composio' || commandPath.startsWith('dev');
384
+const firstOf = (values: ReadonlyArray<string>) => values[0];
385
386
/**
495
- * Tool slug positional of an execute-family invocation, so the CLI bootstrap
496
- * can resolve the toolkit slug once and stamp it on the telemetry context for
497
- * the synchronous lifecycle event builders.
387
+ * How each family that describes an input argument finds it in the input `effect/cli` parsed for
388
+ * the command (see `CliCommandTelemetryContext.argument`).
389
*/
499
-export const getExecuteCommandToolSlug = (
500
- context: CliCommandTelemetryContext
390
+const FAMILY_ARGUMENTS: Partial<
391
+ Record<TelemetryFamily, (input: unknown) => Option.Option<string>>
392
+> = {
393
+ execute: input =>
394
+ Option.map(
395
+ Schema.decodeUnknownOption(Schema.Struct({ slug: Schema.String }))(input),
396
+ ({ slug }) => slug
397
+ ),
398
+ search: input =>
399
+ Option.flatMap(
400
+ Schema.decodeUnknownOption(Schema.Struct({ query: Schema.Array(Schema.String) }))(input),
401
+ ({ query }) => Option.fromNullishOr(firstOf(query))
402
+ ),
403
+ link: input =>
404
+ Option.flatMap(
405
+ Schema.decodeUnknownOption(Schema.Struct({ toolkit: Schema.Option(Schema.String) }))(input),
406
+ ({ toolkit }) => toolkit
407
+ ),
408
+ proxy: input =>
409
+ Option.map(
410
+ Schema.decodeUnknownOption(Schema.Struct({ endpoint: Schema.String }))(input),
411
+ ({ endpoint }) => endpoint
412
+ ),
413
+};
414
+
415
+const familyArgument = (
416
+ family: TelemetryFamily,
417
+ input: Option.Option<unknown>
418
): string | undefined =>
502
- isExecuteCommand(context.commandPath) ? getTrailingPositionals(context)[0] : undefined;
419
+ Option.getOrUndefined(
420
+ Option.flatMap(input, parsed =>
421
+ Option.flatMap(Option.fromNullishOr(FAMILY_ARGUMENTS[family]), argument => argument(parsed))
422
+ )
423
+ );
424
425
/**
505
- * Builds the telemetry context of the running command.
426
+ * Builds the telemetry context of the command `identity` names, with the input `effect/cli`
427
+ * parsed for it (none for help, version, and parse failures).
428
*
429
* `invocation` is read from config by the caller and stamped here so every synchronous event
430
* builder below takes the origin as an input rather than consulting process-wide state.
431
*/
510
-export const createCliCommandTelemetryContext = (
511
- argv: ReadonlyArray<string>,
512
- cliVersion: string,
513
- terminal: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean },
514
- invocation: CliInvocationContext
515
-): CliCommandTelemetryContext => {
516
- const commandPath = extractCommandPath(argv);
432
+export const createCliCommandTelemetryContext = (params: {
433
+ readonly argv: ReadonlyArray<string>;
434
+ readonly cliVersion: string;
435
+ readonly terminal: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean };
436
+ readonly invocation: CliInvocationContext;
437
+ readonly identity: CommandIdentity;
438
+ readonly input: Option.Option<unknown>;
439
+ readonly startedAt: number;
440
+}): CliCommandTelemetryContext => {
441
+ const { argv, invocation, terminal, identity } = params;
442
+ const family = identity.meta.telemetryFamily;
443
return {
444
argv,
519
- cliVersion,
445
+ cliVersion: params.cliVersion,
446
invocationOrigin: invocation.invocationOrigin,
447
parentRunId: invocation.parentRunId,
522
- commandPath,
448
+ commandPath: commandPathOf(identity),
449
+ family,
450
+ argument: familyArgument(family, params.input),
451
flagNames: extractFlagNames(argv),
452
stdoutIsTTY: terminal.stdoutIsTTY,
453
stderrIsTTY: terminal.stderrIsTTY,
526
- startedAt: Date.now(),
527
- runId: commandPath === 'run' ? (invocation.parentRunId ?? crypto.randomUUID()) : undefined,
454
+ startedAt: params.startedAt,
455
+ runId: family === 'run' ? (invocation.parentRunId ?? crypto.randomUUID()) : undefined,
456
};
457
};
458
490
duration_ms: Date.now() - context.startedAt,
491
flag_names: context.flagNames,
492
error_name: errorNameOf(error),
493
+ ...failureReasonProperties(error),
494
});
495
496
type SpecialLifecycleFamily = {
568
- readonly match: (commandPath: string) => boolean;
497
readonly invokedEventName: CliAnalyticsEventName;
498
readonly succeededEventName: CliAnalyticsEventName;
499
readonly failedEventName: CliAnalyticsEventName;
500
readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;
501
};
502
575
-const SPECIAL_LIFECYCLE_FAMILIES: ReadonlyArray<SpecialLifecycleFamily> = [
576
- {
577
- match: isExecuteCommand,
503
+const SPECIAL_LIFECYCLE_FAMILIES: Record<
504
+ Exclude<TelemetryFamily, 'command'>,
505
+ SpecialLifecycleFamily
506
+> = {
507
+ execute: {
508
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_INVOKED,
509
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_SUCCEEDED,
510
failedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_FAILED,
511
getProperties: getExecuteCommandProperties,
512
},
583
- {
584
- match: isSearchCommand,
513
+ search: {
514
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_INVOKED,
515
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_SUCCEEDED,
516
failedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_FAILED,
517
getProperties: getSearchCommandProperties,
518
},
590
- {
591
- match: isLinkCommand,
519
+ link: {
520
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_INVOKED,
521
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_SUCCEEDED,
522
failedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_FAILED,
523
getProperties: getLinkCommandProperties,
524
},
597
- {
598
- match: isLoginCommand,
525
+ login: {
526
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_INVOKED,
527
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_SUCCEEDED,
528
failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_FAILED,
529
getProperties: getLoginCommandProperties,
530
},
604
- {
605
- match: isLogoutCommand,
531
+ logout: {
532
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_INVOKED,
533
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_SUCCEEDED,
534
failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_FAILED,
535
getProperties: getLogoutCommandProperties,
536
},
611
- {
612
- match: isProxyCommand,
537
+ proxy: {
538
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_INVOKED,
539
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_SUCCEEDED,
540
failedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_FAILED,
541
getProperties: getProxyCommandProperties,
542
},
618
- {
619
- match: isRunCommand,
543
+ run: {
544
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_INVOKED,
545
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_SUCCEEDED,
546
failedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_FAILED,
547
getProperties: getRunCommandProperties,
548
},
625
- {
626
- match: isInstallCommand,
549
+ install: {
550
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_INVOKED,
551
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_SUCCEEDED,
552
failedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_FAILED,
553
getProperties: getInstallCommandProperties,
554
},
632
- {
633
- match: isSetupCommand,
555
+ setup: {
556
invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_INVOKED,
557
succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_SUCCEEDED,
558
failedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_FAILED,
559
getProperties: getSetupCommandProperties,
560
},
639
-];
561
+};
562
641
-const getSpecialLifecycleFamily = (commandPath: string): SpecialLifecycleFamily | undefined =>
642
- SPECIAL_LIFECYCLE_FAMILIES.find(family => family.match(commandPath));
563
+const getSpecialLifecycleFamily = (
564
+ context: CliCommandTelemetryContext
565
+): SpecialLifecycleFamily | undefined =>
566
+ context.family === 'command' ? undefined : SPECIAL_LIFECYCLE_FAMILIES[context.family];
567
568
export const getPrimaryLifecycleInvokedEvent = (
569
context: CliCommandTelemetryContext
570
): TrackEvent => {
647
- const family = getSpecialLifecycleFamily(context.commandPath);
648
- if (!family || isGenericOnlyCommand(context.commandPath)) {
571
+ const family = getSpecialLifecycleFamily(context);
572
+ if (!family) {
573
return getCliCommandInvokedEvent(context);
574
}
575
return buildEvent(family.invokedEventName, family.getProperties(context));
578
export const getPrimaryLifecycleSucceededEvent = (
579
context: CliCommandTelemetryContext
580
): TrackEvent => {
657
- const family = getSpecialLifecycleFamily(context.commandPath);
658
- if (!family || isGenericOnlyCommand(context.commandPath)) {
581
+ const family = getSpecialLifecycleFamily(context);
582
+ if (!family) {
583
return getCliCommandSucceededEvent(context);
584
}
585
return buildEvent(family.succeededEventName, family.getProperties(context));
589
context: CliCommandTelemetryContext,
590
error: unknown
591
): TrackEvent => {
668
- const family = getSpecialLifecycleFamily(context.commandPath);
669
- if (!family || isGenericOnlyCommand(context.commandPath)) {
592
+ const family = getSpecialLifecycleFamily(context);
593
+ if (!family) {
594
return getCliCommandFailedEvent(context, error);
595
}
596
return buildEvent(family.failedEventName, {