1
import type { CliCommandTelemetryContext, TrackEvent } from './types';
2
+import { APP_VERSION } from 'src/constants';
3
+import { inferSkillReleaseChannel } from 'src/effects/install-skill';
4
import { ToolInputValidationError } from 'src/services/tool-input-validation';
5
import { toolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
6
46
CLI_TOOL_INVOCATION_FAILED: 'CLI_TOOL_INVOCATION_FAILED',
47
} as const;
48
49
+type CliAnalyticsEventName = (typeof CLI_ANALYTICS_EVENTS)[keyof typeof CLI_ANALYTICS_EVENTS];
50
+
51
+// Contract with the downstream metrics flow page: stage values group the
52
+// adoption funnel, so renaming or removing one is a breaking change there.
53
+export const CLI_JOURNEY_STAGES = [
54
+ 'install',
55
+ 'setup',
56
+ 'login',
57
+ 'connect',
58
+ 'execute',
59
+ 'other',
60
+] as const;
61
+
62
+export type CliJourneyStage = (typeof CLI_JOURNEY_STAGES)[number];
63
+
64
+export const CLI_EVENT_JOURNEY_STAGES = {
65
+ CLI_COMMAND_INVOKED: 'other',
66
+ CLI_COMMAND_SUCCEEDED: 'other',
67
+ CLI_COMMAND_FAILED: 'other',
68
+ CLI_EXECUTE_INVOKED: 'execute',
69
+ CLI_EXECUTE_SUCCEEDED: 'execute',
70
+ CLI_EXECUTE_FAILED: 'execute',
71
+ CLI_SEARCH_INVOKED: 'other',
72
+ CLI_SEARCH_SUCCEEDED: 'other',
73
+ CLI_SEARCH_FAILED: 'other',
74
+ CLI_LINK_INVOKED: 'connect',
75
+ CLI_LINK_SUCCEEDED: 'connect',
76
+ CLI_LINK_FAILED: 'connect',
77
+ CLI_LOGIN_INVOKED: 'login',
78
+ CLI_LOGIN_SUCCEEDED: 'login',
79
+ CLI_LOGIN_FAILED: 'login',
80
+ CLI_LOGOUT_INVOKED: 'other',
81
+ CLI_LOGOUT_SUCCEEDED: 'other',
82
+ CLI_LOGOUT_FAILED: 'other',
83
+ CLI_PROXY_INVOKED: 'other',
84
+ CLI_PROXY_SUCCEEDED: 'other',
85
+ CLI_PROXY_FAILED: 'other',
86
+ CLI_RUN_INVOKED: 'other',
87
+ CLI_RUN_SUCCEEDED: 'other',
88
+ CLI_RUN_FAILED: 'other',
89
+ CLI_INSTALL_INVOKED: 'install',
90
+ CLI_INSTALL_SUCCEEDED: 'install',
91
+ CLI_INSTALL_FAILED: 'install',
92
+ CLI_SETUP_INVOKED: 'setup',
93
+ CLI_SETUP_SUCCEEDED: 'setup',
94
+ CLI_SETUP_FAILED: 'setup',
95
+ CLI_SETUP_HOST_DETECTED: 'setup',
96
+ CLI_SETUP_CANCELLED: 'setup',
97
+ CLI_SETUP_SKIPPED: 'setup',
98
+ CLI_PLUGIN_SETUP_SUCCEEDED: 'setup',
99
+ CLI_PLUGIN_SETUP_FAILED: 'setup',
100
+ CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'setup',
101
+ CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'execute',
102
+ CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'execute',
103
+ CLI_TOOL_INVOCATION_FAILED: 'execute',
104
+} as const satisfies Record<CliAnalyticsEventName, CliJourneyStage>;
105
+
106
+const buildEvent = (
107
+ name: CliAnalyticsEventName,
108
+ properties: Record<string, unknown>
109
+): TrackEvent => ({
110
+ name,
111
+ properties: {
112
+ ...properties,
113
+ journey_stage: CLI_EVENT_JOURNEY_STAGES[name],
114
+ cli_channel: inferSkillReleaseChannel(APP_VERSION),
115
+ },
116
+});
117
+
118
const KNOWN_COMMAND_TOKENS = new Set([
119
'version',
120
'upgrade',
471
: undefined,
472
});
473
403
-const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent => ({
404
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED,
405
- properties: {
474
+const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent =>
475
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED, {
476
source: 'cli',
477
invocation_origin: getInvocationOrigin(),
478
cli_version: context.cliVersion,
481
arg_count: Math.max(0, context.argv.length - 2),
482
stdout_is_tty: context.stdoutIsTTY,
483
stderr_is_tty: context.stderrIsTTY,
414
- },
415
-});
484
+ });
485
417
-const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent => ({
418
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED,
419
- properties: {
486
+const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent =>
487
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED, {
488
source: 'cli',
489
invocation_origin: getInvocationOrigin(),
490
cli_version: context.cliVersion,
491
command_path: context.commandPath,
492
duration_ms: Date.now() - context.startedAt,
493
flag_names: context.flagNames,
426
- },
427
-});
494
+ });
495
496
const getCliCommandFailedEvent = (
497
context: CliCommandTelemetryContext,
498
error: unknown
432
-): TrackEvent => ({
433
- name: CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED,
434
- properties: {
499
+): TrackEvent =>
500
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED, {
501
source: 'cli',
502
invocation_origin: getInvocationOrigin(),
503
cli_version: context.cliVersion,
506
flag_names: context.flagNames,
507
error_name: errorNameOf(error),
508
error_message: errorMessageOf(error),
443
- },
444
-});
509
+ });
510
511
type SpecialLifecycleFamily = {
512
readonly match: (commandPath: string) => boolean;
448
- readonly invokedEventName: string;
449
- readonly succeededEventName: string;
450
- readonly failedEventName: string;
513
+ readonly invokedEventName: CliAnalyticsEventName;
514
+ readonly succeededEventName: CliAnalyticsEventName;
515
+ readonly failedEventName: CliAnalyticsEventName;
516
readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;
517
};
518
592
if (!family || isGenericOnlyCommand(context.commandPath)) {
593
return getCliCommandInvokedEvent(context);
594
}
530
- return {
531
- name: family.invokedEventName,
532
- properties: family.getProperties(context),
533
- };
595
+ return buildEvent(family.invokedEventName, family.getProperties(context));
596
};
597
598
export const getPrimaryLifecycleSucceededEvent = (
602
if (!family || isGenericOnlyCommand(context.commandPath)) {
603
return getCliCommandSucceededEvent(context);
604
}
543
- return {
544
- name: family.succeededEventName,
545
- properties: family.getProperties(context),
546
- };
605
+ return buildEvent(family.succeededEventName, family.getProperties(context));
606
};
607
608
export const getPrimaryLifecycleFailedEvent = (
613
if (!family || isGenericOnlyCommand(context.commandPath)) {
614
return getCliCommandFailedEvent(context, error);
615
}
557
- return {
558
- name: family.failedEventName,
559
- properties: {
560
- ...family.getProperties(context),
561
- error_name: errorNameOf(error),
562
- error_message: errorMessageOf(error),
563
- },
564
- };
616
+ return buildEvent(family.failedEventName, {
617
+ ...family.getProperties(context),
618
+ error_name: errorNameOf(error),
619
+ error_message: errorMessageOf(error),
620
+ });
621
};
622
623
export const getPluginLifecycleSucceededEvent = (params: {
625
readonly target: 'claude' | 'codex';
626
readonly action: 'installed' | 'enabled' | 'configured' | 'uninstalled';
627
readonly cliVersion: string;
572
-}): TrackEvent => ({
573
- name:
628
+}): TrackEvent =>
629
+ buildEvent(
630
params.operation === 'uninstall'
631
? CLI_ANALYTICS_EVENTS.CLI_PLUGIN_UNINSTALL_SUCCEEDED
632
: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_SUCCEEDED,
577
- properties: {
578
- source: 'cli',
579
- invocation_origin: getInvocationOrigin(),
580
- cli_version: params.cliVersion,
581
- command_path: 'setup',
582
- operation: params.operation,
583
- agent_host: params.target,
584
- action: params.action,
585
- },
586
-});
633
+ {
634
+ source: 'cli',
635
+ invocation_origin: getInvocationOrigin(),
636
+ cli_version: params.cliVersion,
637
+ command_path: 'setup',
638
+ operation: params.operation,
639
+ agent_host: params.target,
640
+ action: params.action,
641
+ }
642
+ );
643
644
export const getPluginLifecycleFailedEvent = (params: {
645
readonly operation: 'setup' | 'uninstall';
647
readonly phase: 'install' | 'uninstall';
648
readonly error: unknown;
649
readonly cliVersion: string;
594
-}): TrackEvent => ({
595
- name: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED,
596
- properties: {
650
+}): TrackEvent =>
651
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED, {
652
source: 'cli',
653
invocation_origin: getInvocationOrigin(),
654
cli_version: params.cliVersion,
658
phase: params.phase,
659
error_name: errorNameOf(params.error),
660
error_message: errorMessageOf(params.error),
606
- },
607
-});
661
+ });
662
663
export const getSetupHostDetectedEvent = (params: {
664
readonly operation: 'setup' | 'uninstall';
670
readonly unsupportedReasonCode?:
671
'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown';
672
readonly cliVersion: string;
619
-}): TrackEvent => ({
620
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED,
621
- properties: {
673
+}): TrackEvent =>
674
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED, {
675
source: 'cli',
676
invocation_origin: getInvocationOrigin(),
677
cli_version: params.cliVersion,
683
supported: params.supported,
684
host_version: params.hostVersion,
685
unsupported_reason_code: params.unsupportedReasonCode,
633
- },
634
-});
686
+ });
687
688
export const getSetupCancelledEvent = (params: {
689
readonly operation: 'setup' | 'uninstall';
690
readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';
691
readonly cliVersion: string;
640
-}): TrackEvent => ({
641
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED,
642
- properties: {
692
+}): TrackEvent =>
693
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED, {
694
source: 'cli',
695
invocation_origin: getInvocationOrigin(),
696
cli_version: params.cliVersion,
698
operation: params.operation,
699
requested_target: params.requestedTarget,
700
reason: 'user_declined',
650
- },
651
-});
701
+ });
702
703
export const getSetupSkippedEvent = (params: {
704
readonly operation: 'setup' | 'uninstall';
705
readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';
706
readonly cliVersion: string;
657
-}): TrackEvent => ({
658
- name: CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED,
659
- properties: {
707
+}): TrackEvent =>
708
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED, {
709
source: 'cli',
710
invocation_origin: getInvocationOrigin(),
711
cli_version: params.cliVersion,
713
operation: params.operation,
714
requested_target: params.requestedTarget,
715
reason: 'no_host_detected',
667
- },
668
-});
716
+ });
717
718
export const getToolExecuteValidationFailedEvent = (params: {
719
readonly toolSlug: string;
724
readonly stage: 'dry_run' | 'validation' | 'execution';
725
readonly failureOrigin: 'fast_fail' | 'main_endpoint';
726
readonly logId?: string;
679
-}): TrackEvent => ({
680
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED,
681
- properties: {
727
+}): TrackEvent =>
728
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED, {
729
source: 'cli',
730
invocation_origin: getInvocationOrigin(),
731
tool_slug: params.toolSlug,
740
unknown_keys: extractUnknownKeys(params.error.issues),
741
schema_path: params.error.schemaPath,
742
...argumentShape(params.args),
696
- },
697
-});
743
+ });
744
745
export const isMaybeToolNotFoundError = (params: {
746
readonly message?: string;
777
readonly status?: number;
778
readonly apiCode?: number;
779
readonly message?: string;
734
-}): TrackEvent => ({
735
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND,
736
- properties: {
780
+}): TrackEvent =>
781
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND, {
782
source: 'cli',
783
invocation_origin: getInvocationOrigin(),
784
tool_slug: params.toolSlug,
793
api_error_code: params.apiCode,
794
error_message: params.message?.slice(0, 500),
795
...argumentShape(params.args),
751
- },
752
-});
796
+ });
797
798
export const getToolExecuteFailedEvent = (params: {
799
readonly toolSlug: string;
809
readonly message?: string;
810
readonly errorName?: string;
811
readonly isNoConnectionError?: boolean;
768
-}): TrackEvent => ({
769
- name: CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED,
770
- properties: {
812
+}): TrackEvent =>
813
+ buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED, {
814
source: 'cli',
815
invocation_origin: getInvocationOrigin(),
816
tool_slug: params.toolSlug,
827
error_message: params.message?.slice(0, 500),
828
is_no_connection_error: Boolean(params.isNoConnectionError),
829
...argumentShape(params.args),
787
- },
788
-});
830
+ });