Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { cliAnalyticsProvenance } from 'src/services/client-provenance'; |
| 2 | import { Option } 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'; |
| 9 | import type { CliInvocationContext } from 'src/services/runtime-cli-context'; |
| 10 | import { ChildProcessExited, ChildProcessSignaled } from 'src/effects/child-process-exited'; |
| 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'; |
| 14 | |
| 15 | export const CLI_ANALYTICS_EVENTS = { |
| 16 | CLI_COMMAND_INVOKED: 'CLI_COMMAND_INVOKED', |
| 17 | CLI_COMMAND_SUCCEEDED: 'CLI_COMMAND_SUCCEEDED', |
| 18 | CLI_COMMAND_FAILED: 'CLI_COMMAND_FAILED', |
| 19 | CLI_EXECUTE_INVOKED: 'CLI_EXECUTE_INVOKED', |
| 20 | CLI_EXECUTE_SUCCEEDED: 'CLI_EXECUTE_SUCCEEDED', |
| 21 | CLI_EXECUTE_FAILED: 'CLI_EXECUTE_FAILED', |
| 22 | CLI_SEARCH_INVOKED: 'CLI_SEARCH_INVOKED', |
| 23 | CLI_SEARCH_SUCCEEDED: 'CLI_SEARCH_SUCCEEDED', |
| 24 | CLI_SEARCH_FAILED: 'CLI_SEARCH_FAILED', |
| 25 | CLI_LINK_INVOKED: 'CLI_LINK_INVOKED', |
| 26 | CLI_LINK_SUCCEEDED: 'CLI_LINK_SUCCEEDED', |
| 27 | CLI_LINK_FAILED: 'CLI_LINK_FAILED', |
| 28 | CLI_LOGIN_INVOKED: 'CLI_LOGIN_INVOKED', |
| 29 | CLI_LOGIN_SUCCEEDED: 'CLI_LOGIN_SUCCEEDED', |
| 30 | CLI_LOGIN_FAILED: 'CLI_LOGIN_FAILED', |
| 31 | CLI_LOGOUT_INVOKED: 'CLI_LOGOUT_INVOKED', |
| 32 | CLI_LOGOUT_SUCCEEDED: 'CLI_LOGOUT_SUCCEEDED', |
| 33 | CLI_LOGOUT_FAILED: 'CLI_LOGOUT_FAILED', |
| 34 | CLI_PROXY_INVOKED: 'CLI_PROXY_INVOKED', |
| 35 | CLI_PROXY_SUCCEEDED: 'CLI_PROXY_SUCCEEDED', |
| 36 | CLI_PROXY_FAILED: 'CLI_PROXY_FAILED', |
| 37 | CLI_RUN_INVOKED: 'CLI_RUN_INVOKED', |
| 38 | CLI_RUN_SUCCEEDED: 'CLI_RUN_SUCCEEDED', |
| 39 | CLI_RUN_FAILED: 'CLI_RUN_FAILED', |
| 40 | CLI_INSTALL_INVOKED: 'CLI_INSTALL_INVOKED', |
| 41 | CLI_INSTALL_SUCCEEDED: 'CLI_INSTALL_SUCCEEDED', |
| 42 | CLI_INSTALL_FAILED: 'CLI_INSTALL_FAILED', |
| 43 | CLI_SETUP_INVOKED: 'CLI_SETUP_INVOKED', |
| 44 | CLI_SETUP_SUCCEEDED: 'CLI_SETUP_SUCCEEDED', |
| 45 | CLI_SETUP_FAILED: 'CLI_SETUP_FAILED', |
| 46 | CLI_SETUP_HOST_DETECTED: 'CLI_SETUP_HOST_DETECTED', |
| 47 | CLI_SETUP_CANCELLED: 'CLI_SETUP_CANCELLED', |
| 48 | CLI_SETUP_SKIPPED: 'CLI_SETUP_SKIPPED', |
| 49 | CLI_PLUGIN_SETUP_SUCCEEDED: 'CLI_PLUGIN_SETUP_SUCCEEDED', |
| 50 | CLI_PLUGIN_SETUP_FAILED: 'CLI_PLUGIN_SETUP_FAILED', |
| 51 | CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'CLI_PLUGIN_UNINSTALL_SUCCEEDED', |
| 52 | CLI_PLUGIN_HINT_SHOWN: 'CLI_PLUGIN_HINT_SHOWN', |
| 53 | CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'CLI_TOOL_INVOCATION_VALIDATION_FAILED', |
| 54 | CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'CLI_TOOL_INVOCATION_TOOL_NOT_FOUND', |
| 55 | CLI_TOOL_INVOCATION_FAILED: 'CLI_TOOL_INVOCATION_FAILED', |
| 56 | } as const; |
| 57 | |
| 58 | type CliAnalyticsEventName = (typeof CLI_ANALYTICS_EVENTS)[keyof typeof CLI_ANALYTICS_EVENTS]; |
| 59 | |
| 60 | export const CLI_JOURNEY_STAGES = [ |
| 61 | 'install', |
| 62 | 'setup', |
| 63 | 'login', |
| 64 | 'connect', |
| 65 | 'execute', |
| 66 | 'other', |
| 67 | ] as const; |
| 68 | |
| 69 | export type CliJourneyStage = (typeof CLI_JOURNEY_STAGES)[number]; |
| 70 | |
| 71 | export const CLI_EVENT_JOURNEY_STAGES = { |
| 72 | CLI_COMMAND_INVOKED: 'other', |
| 73 | CLI_COMMAND_SUCCEEDED: 'other', |
| 74 | CLI_COMMAND_FAILED: 'other', |
| 75 | CLI_EXECUTE_INVOKED: 'execute', |
| 76 | CLI_EXECUTE_SUCCEEDED: 'execute', |
| 77 | CLI_EXECUTE_FAILED: 'execute', |
| 78 | CLI_SEARCH_INVOKED: 'other', |
| 79 | CLI_SEARCH_SUCCEEDED: 'other', |
| 80 | CLI_SEARCH_FAILED: 'other', |
| 81 | CLI_LINK_INVOKED: 'connect', |
| 82 | CLI_LINK_SUCCEEDED: 'connect', |
| 83 | CLI_LINK_FAILED: 'connect', |
| 84 | CLI_LOGIN_INVOKED: 'login', |
| 85 | CLI_LOGIN_SUCCEEDED: 'login', |
| 86 | CLI_LOGIN_FAILED: 'login', |
| 87 | CLI_LOGOUT_INVOKED: 'other', |
| 88 | CLI_LOGOUT_SUCCEEDED: 'other', |
| 89 | CLI_LOGOUT_FAILED: 'other', |
| 90 | CLI_PROXY_INVOKED: 'other', |
| 91 | CLI_PROXY_SUCCEEDED: 'other', |
| 92 | CLI_PROXY_FAILED: 'other', |
| 93 | CLI_RUN_INVOKED: 'other', |
| 94 | CLI_RUN_SUCCEEDED: 'other', |
| 95 | CLI_RUN_FAILED: 'other', |
| 96 | CLI_INSTALL_INVOKED: 'install', |
| 97 | CLI_INSTALL_SUCCEEDED: 'install', |
| 98 | CLI_INSTALL_FAILED: 'install', |
| 99 | CLI_SETUP_INVOKED: 'setup', |
| 100 | CLI_SETUP_SUCCEEDED: 'setup', |
| 101 | CLI_SETUP_FAILED: 'setup', |
| 102 | CLI_SETUP_HOST_DETECTED: 'setup', |
| 103 | CLI_SETUP_CANCELLED: 'setup', |
| 104 | CLI_SETUP_SKIPPED: 'setup', |
| 105 | CLI_PLUGIN_SETUP_SUCCEEDED: 'setup', |
| 106 | CLI_PLUGIN_SETUP_FAILED: 'setup', |
| 107 | CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'setup', |
| 108 | CLI_PLUGIN_HINT_SHOWN: 'setup', |
| 109 | CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'execute', |
| 110 | CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'execute', |
| 111 | CLI_TOOL_INVOCATION_FAILED: 'execute', |
| 112 | } as const satisfies Record<CliAnalyticsEventName, CliJourneyStage>; |
| 113 | |
| 114 | let cliAnalyticsVersion = APP_VERSION; |
| 115 | let cliChannel = inferSkillReleaseChannel(APP_VERSION); |
| 116 | |
| 117 | /** |
| 118 | * Event builders are synchronous, so the CLI bootstrap injects the version |
| 119 | * resolved from release-tag.txt before any command can emit telemetry. |
| 120 | */ |
| 121 | export const configureCliAnalyticsReleaseVersion = (version: string): void => { |
| 122 | cliAnalyticsVersion = version; |
| 123 | cliChannel = inferSkillReleaseChannel(version); |
| 124 | }; |
| 125 | |
| 126 | const buildEvent = ( |
| 127 | name: CliAnalyticsEventName, |
| 128 | properties: Record<string, unknown> |
| 129 | ): TrackEvent => ({ |
| 130 | name, |
| 131 | properties: { |
| 132 | ...properties, |
| 133 | ...cliAnalyticsProvenance( |
| 134 | typeof properties.cli_version === 'string' ? properties.cli_version : cliAnalyticsVersion |
| 135 | ), |
| 136 | // Command events can describe offline or mixed work. Do not pretend they |
| 137 | // each represent one HTTP request. |
| 138 | execution_channel: |
| 139 | typeof properties.command_path === 'string' && |
| 140 | [ |
| 141 | 'execute', |
| 142 | 'search', |
| 143 | 'link', |
| 144 | 'proxy', |
| 145 | 'dev playground-execute', |
| 146 | 'dev toolkits search', |
| 147 | 'dev connected-accounts link', |
| 148 | ].includes(properties.command_path) |
| 149 | ? 'tool_router' |
| 150 | : 'unknown', |
| 151 | journey_stage: CLI_EVENT_JOURNEY_STAGES[name], |
| 152 | cli_channel: cliChannel, |
| 153 | }, |
| 154 | }); |
| 155 | |
| 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([ |
| 159 | 1147, // MCP_ToolNotFound |
| 160 | 1800, // ActionExecute_ToolNotFound |
| 161 | 2301, // Labs_ToolNotFound |
| 162 | 2306, // Labs_InvalidToolName |
| 163 | 2401, // Tool_ToolNotFound |
| 164 | 3703, // ComposioTools_ToolNotFound |
| 165 | 4301, // ToolRouterV2_ToolNotFound |
| 166 | ]); |
| 167 | const TOOL_VALIDATION_CODES: ReadonlySet<number> = new Set([ |
| 168 | 1142, // MCP_ValidationError |
| 169 | 1149, // MCP_InvalidParameter |
| 170 | 1607, // Upstream_ValidationError |
| 171 | 3702, // ComposioTools_ValidationError |
| 172 | ]); |
| 173 | |
| 174 | const argumentShape = (args: Record<string, unknown>) => { |
| 175 | const keys = Object.keys(args).sort(); |
| 176 | return { |
| 177 | argument_key_count: keys.length, |
| 178 | argument_keys: keys.slice(0, 50), |
| 179 | }; |
| 180 | }; |
| 181 | |
| 182 | const extractIssueLocations = (issues: ReadonlyArray<string>): ReadonlyArray<string> => |
| 183 | [ |
| 184 | ...new Set( |
| 185 | issues |
| 186 | .map(issue => issue.match(/^([^:]+):/u)?.[1]?.trim()) |
| 187 | .filter((value): value is string => typeof value === 'string' && value.length > 0) |
| 188 | ), |
| 189 | ].slice(0, 20); |
| 190 | |
| 191 | const extractUnknownKeys = (issues: ReadonlyArray<string>): ReadonlyArray<string> => |
| 192 | [ |
| 193 | ...new Set( |
| 194 | issues |
| 195 | .map(issue => issue.match(/Unknown key "([^"]+)"/u)?.[1]) |
| 196 | .filter((value): value is string => typeof value === 'string' && value.length > 0) |
| 197 | ), |
| 198 | ].slice(0, 20); |
| 199 | |
| 200 | const errorNameOf = (error: unknown): string => |
| 201 | error instanceof Error && error.name ? error.name : 'UnknownError'; |
| 202 | |
| 203 | const failureReasonProperties = (error: unknown) => { |
| 204 | // `effect/cli` rejected argv: no command ran, and the event's command path is the one the |
| 205 | // parser reached (`CliError.ShowHelp.commandPath`). A bare group's help carries no errors. |
| 206 | if (error instanceof CliError.ShowHelp && error.errors.length > 0) { |
| 207 | return { failure_reason_code: 'parse_error' }; |
| 208 | } |
| 209 | if (error instanceof SetupCommandError) return { failure_reason_code: error.reasonCode }; |
| 210 | if (error instanceof ChildProcessExited || error instanceof ChildProcessSignaled) { |
| 211 | return { failure_reason_code: 'child_exit' }; |
| 212 | } |
| 213 | return {}; |
| 214 | }; |
| 215 | |
| 216 | const commandProperties = (context: CliCommandTelemetryContext) => ({ |
| 217 | ...context.options, |
| 218 | source: 'cli', |
| 219 | invocation_origin: context.invocationOrigin, |
| 220 | cli_version: context.cliVersion, |
| 221 | command_path: context.commandPath, |
| 222 | duration_ms: Date.now() - context.startedAt, |
| 223 | }); |
| 224 | |
| 225 | const parentProperties = (context: CliCommandTelemetryContext) => ({ |
| 226 | ...commandProperties(context), |
| 227 | parent_run_id: context.parentRunId, |
| 228 | parent_command: context.parentRunId ? 'run' : undefined, |
| 229 | }); |
| 230 | |
| 231 | const getExecuteCommandProperties = (context: CliCommandTelemetryContext) => { |
| 232 | const slug = context.argument; |
| 233 | return { |
| 234 | ...parentProperties(context), |
| 235 | surface: context.commandPath === 'execute' ? 'root' : 'dev', |
| 236 | tool_slug: slug, |
| 237 | tool_name: slug, |
| 238 | toolkit_slug: |
| 239 | context.toolkitSlug ?? |
| 240 | (typeof slug === 'string' ? guessToolkitFromToolSlug(slug) : undefined), |
| 241 | }; |
| 242 | }; |
| 243 | |
| 244 | const getLinkCommandProperties = (context: CliCommandTelemetryContext) => ({ |
| 245 | ...parentProperties(context), |
| 246 | toolkit: context.argument, |
| 247 | }); |
| 248 | |
| 249 | const getRunCommandProperties = (context: CliCommandTelemetryContext) => ({ |
| 250 | ...commandProperties(context), |
| 251 | run_id: context.runId, |
| 252 | }); |
| 253 | |
| 254 | const getSetupCommandProperties = (context: CliCommandTelemetryContext) => ({ |
| 255 | ...commandProperties(context), |
| 256 | stdout_is_tty: context.stdoutIsTTY, |
| 257 | }); |
| 258 | |
| 259 | /** |
| 260 | * Builds the telemetry context of the command `identity` names, with the input `effect/cli` |
| 261 | * parsed for it (none for help, version, and parse failures). |
| 262 | * |
| 263 | * `invocation` is read from config by the caller and stamped here so every synchronous event |
| 264 | * builder below takes the origin as an input rather than consulting process-wide state. |
| 265 | */ |
| 266 | export const createCliCommandTelemetryContext = (params: { |
| 267 | readonly argv: ReadonlyArray<string>; |
| 268 | readonly cliVersion: string; |
| 269 | readonly terminal: { readonly stdoutIsTTY: boolean; readonly stderrIsTTY: boolean }; |
| 270 | readonly invocation: CliInvocationContext; |
| 271 | readonly identity: CommandIdentity; |
| 272 | readonly input: Option.Option<unknown>; |
| 273 | readonly startedAt: number; |
| 274 | }): CliCommandTelemetryContext => { |
| 275 | const { argv, invocation, terminal, identity } = params; |
| 276 | const family = identity.meta.telemetryFamily; |
| 277 | return { |
| 278 | argv, |
| 279 | cliVersion: params.cliVersion, |
| 280 | invocationOrigin: invocation.invocationOrigin, |
| 281 | parentRunId: invocation.parentRunId, |
| 282 | commandPath: commandPathOf(identity), |
| 283 | family, |
| 284 | ...Option.getOrElse( |
| 285 | Option.flatMap(params.input, input => |
| 286 | Option.map(Option.fromNullishOr(identity.meta.telemetryInput), project => project(input)) |
| 287 | ), |
| 288 | () => ({ options: {}, flagNames: [] }) |
| 289 | ), |
| 290 | stdoutIsTTY: terminal.stdoutIsTTY, |
| 291 | stderrIsTTY: terminal.stderrIsTTY, |
| 292 | startedAt: params.startedAt, |
| 293 | runId: family === 'run' ? (invocation.parentRunId ?? crypto.randomUUID()) : undefined, |
| 294 | }; |
| 295 | }; |
| 296 | |
| 297 | const getCliCommandInvokedEvent = (context: CliCommandTelemetryContext): TrackEvent => |
| 298 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_INVOKED, { |
| 299 | source: 'cli', |
| 300 | invocation_origin: context.invocationOrigin, |
| 301 | cli_version: context.cliVersion, |
| 302 | command_path: context.commandPath, |
| 303 | flag_names: context.flagNames, |
| 304 | arg_count: Math.max(0, context.argv.length - 2), |
| 305 | stdout_is_tty: context.stdoutIsTTY, |
| 306 | stderr_is_tty: context.stderrIsTTY, |
| 307 | }); |
| 308 | |
| 309 | const getCliCommandSucceededEvent = (context: CliCommandTelemetryContext): TrackEvent => |
| 310 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_SUCCEEDED, { |
| 311 | source: 'cli', |
| 312 | invocation_origin: context.invocationOrigin, |
| 313 | cli_version: context.cliVersion, |
| 314 | command_path: context.commandPath, |
| 315 | duration_ms: Date.now() - context.startedAt, |
| 316 | flag_names: context.flagNames, |
| 317 | }); |
| 318 | |
| 319 | const getCliCommandFailedEvent = ( |
| 320 | context: CliCommandTelemetryContext, |
| 321 | error: unknown |
| 322 | ): TrackEvent => |
| 323 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_COMMAND_FAILED, { |
| 324 | source: 'cli', |
| 325 | invocation_origin: context.invocationOrigin, |
| 326 | cli_version: context.cliVersion, |
| 327 | command_path: context.commandPath, |
| 328 | duration_ms: Date.now() - context.startedAt, |
| 329 | flag_names: context.flagNames, |
| 330 | error_name: errorNameOf(error), |
| 331 | ...failureReasonProperties(error), |
| 332 | }); |
| 333 | |
| 334 | type SpecialLifecycleFamily = { |
| 335 | readonly invokedEventName: CliAnalyticsEventName; |
| 336 | readonly succeededEventName: CliAnalyticsEventName; |
| 337 | readonly failedEventName: CliAnalyticsEventName; |
| 338 | readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>; |
| 339 | }; |
| 340 | |
| 341 | const SPECIAL_LIFECYCLE_FAMILIES: Record< |
| 342 | Exclude<TelemetryFamily, 'command'>, |
| 343 | SpecialLifecycleFamily |
| 344 | > = { |
| 345 | execute: { |
| 346 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_INVOKED, |
| 347 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_SUCCEEDED, |
| 348 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_EXECUTE_FAILED, |
| 349 | getProperties: getExecuteCommandProperties, |
| 350 | }, |
| 351 | search: { |
| 352 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_INVOKED, |
| 353 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_SUCCEEDED, |
| 354 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_SEARCH_FAILED, |
| 355 | getProperties: parentProperties, |
| 356 | }, |
| 357 | link: { |
| 358 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_INVOKED, |
| 359 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_SUCCEEDED, |
| 360 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_LINK_FAILED, |
| 361 | getProperties: getLinkCommandProperties, |
| 362 | }, |
| 363 | login: { |
| 364 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_INVOKED, |
| 365 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_SUCCEEDED, |
| 366 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGIN_FAILED, |
| 367 | getProperties: commandProperties, |
| 368 | }, |
| 369 | logout: { |
| 370 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_INVOKED, |
| 371 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_SUCCEEDED, |
| 372 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_LOGOUT_FAILED, |
| 373 | getProperties: commandProperties, |
| 374 | }, |
| 375 | proxy: { |
| 376 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_INVOKED, |
| 377 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_SUCCEEDED, |
| 378 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_PROXY_FAILED, |
| 379 | getProperties: commandProperties, |
| 380 | }, |
| 381 | run: { |
| 382 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_INVOKED, |
| 383 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_SUCCEEDED, |
| 384 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_RUN_FAILED, |
| 385 | getProperties: getRunCommandProperties, |
| 386 | }, |
| 387 | install: { |
| 388 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_INVOKED, |
| 389 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_SUCCEEDED, |
| 390 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_INSTALL_FAILED, |
| 391 | getProperties: commandProperties, |
| 392 | }, |
| 393 | setup: { |
| 394 | invokedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_INVOKED, |
| 395 | succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_SUCCEEDED, |
| 396 | failedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_FAILED, |
| 397 | getProperties: getSetupCommandProperties, |
| 398 | }, |
| 399 | }; |
| 400 | |
| 401 | const getSpecialLifecycleFamily = ( |
| 402 | context: CliCommandTelemetryContext |
| 403 | ): SpecialLifecycleFamily | undefined => |
| 404 | context.family === 'command' ? undefined : SPECIAL_LIFECYCLE_FAMILIES[context.family]; |
| 405 | |
| 406 | export const getPrimaryLifecycleInvokedEvent = ( |
| 407 | context: CliCommandTelemetryContext |
| 408 | ): TrackEvent => { |
| 409 | const family = getSpecialLifecycleFamily(context); |
| 410 | if (!family) { |
| 411 | return getCliCommandInvokedEvent(context); |
| 412 | } |
| 413 | return buildEvent(family.invokedEventName, family.getProperties(context)); |
| 414 | }; |
| 415 | |
| 416 | export const getPrimaryLifecycleSucceededEvent = ( |
| 417 | context: CliCommandTelemetryContext |
| 418 | ): TrackEvent => { |
| 419 | const family = getSpecialLifecycleFamily(context); |
| 420 | if (!family) { |
| 421 | return getCliCommandSucceededEvent(context); |
| 422 | } |
| 423 | return buildEvent(family.succeededEventName, family.getProperties(context)); |
| 424 | }; |
| 425 | |
| 426 | export const getPrimaryLifecycleFailedEvent = ( |
| 427 | context: CliCommandTelemetryContext, |
| 428 | error: unknown |
| 429 | ): TrackEvent => { |
| 430 | const family = getSpecialLifecycleFamily(context); |
| 431 | if (!family) { |
| 432 | return getCliCommandFailedEvent(context, error); |
| 433 | } |
| 434 | return buildEvent(family.failedEventName, { |
| 435 | ...family.getProperties(context), |
| 436 | error_name: errorNameOf(error), |
| 437 | ...failureReasonProperties(error), |
| 438 | }); |
| 439 | }; |
| 440 | |
| 441 | export const getPluginHintShownEvent = (params: { |
| 442 | readonly invocationOrigin: string; |
| 443 | readonly cliVersion: string; |
| 444 | readonly commandPath: string; |
| 445 | readonly agentHost: AgentHost; |
| 446 | }): TrackEvent => |
| 447 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_HINT_SHOWN, { |
| 448 | source: 'cli', |
| 449 | invocation_origin: params.invocationOrigin, |
| 450 | cli_version: params.cliVersion, |
| 451 | command_path: params.commandPath, |
| 452 | agent_host: params.agentHost, |
| 453 | }); |
| 454 | |
| 455 | export const getPluginLifecycleSucceededEvent = (params: { |
| 456 | readonly operation: 'setup' | 'uninstall'; |
| 457 | readonly target: 'claude' | 'codex'; |
| 458 | readonly action: 'installed' | 'enabled' | 'configured' | 'uninstalled'; |
| 459 | readonly invocationOrigin: string; |
| 460 | readonly cliVersion: string; |
| 461 | }): TrackEvent => |
| 462 | buildEvent( |
| 463 | params.operation === 'uninstall' |
| 464 | ? CLI_ANALYTICS_EVENTS.CLI_PLUGIN_UNINSTALL_SUCCEEDED |
| 465 | : CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_SUCCEEDED, |
| 466 | { |
| 467 | source: 'cli', |
| 468 | invocation_origin: params.invocationOrigin, |
| 469 | cli_version: params.cliVersion, |
| 470 | command_path: 'setup', |
| 471 | operation: params.operation, |
| 472 | agent_host: params.target, |
| 473 | action: params.action, |
| 474 | } |
| 475 | ); |
| 476 | |
| 477 | export const getPluginLifecycleFailedEvent = (params: { |
| 478 | readonly operation: 'setup' | 'uninstall'; |
| 479 | readonly target: 'claude' | 'codex'; |
| 480 | readonly phase: 'install' | 'uninstall'; |
| 481 | readonly error: unknown; |
| 482 | readonly invocationOrigin: string; |
| 483 | readonly cliVersion: string; |
| 484 | }): TrackEvent => |
| 485 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_SETUP_FAILED, { |
| 486 | source: 'cli', |
| 487 | invocation_origin: params.invocationOrigin, |
| 488 | cli_version: params.cliVersion, |
| 489 | command_path: 'setup', |
| 490 | operation: params.operation, |
| 491 | agent_host: params.target, |
| 492 | phase: params.phase, |
| 493 | error_name: errorNameOf(params.error), |
| 494 | }); |
| 495 | |
| 496 | export const getSetupHostDetectedEvent = (params: { |
| 497 | readonly operation: 'setup' | 'uninstall'; |
| 498 | readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all'; |
| 499 | readonly target: 'claude' | 'codex'; |
| 500 | readonly available: boolean; |
| 501 | readonly supported: boolean; |
| 502 | readonly hostVersion?: string; |
| 503 | readonly unsupportedReasonCode?: |
| 504 | 'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown'; |
| 505 | readonly hostConfigDirPresent?: boolean; |
| 506 | readonly hostBinaryInKnownPaths?: boolean; |
| 507 | readonly invocationOrigin: string; |
| 508 | readonly cliVersion: string; |
| 509 | }): TrackEvent => |
| 510 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_HOST_DETECTED, { |
| 511 | source: 'cli', |
| 512 | invocation_origin: params.invocationOrigin, |
| 513 | cli_version: params.cliVersion, |
| 514 | command_path: 'setup', |
| 515 | operation: params.operation, |
| 516 | requested_target: params.requestedTarget, |
| 517 | agent_host: params.target, |
| 518 | available: params.available, |
| 519 | supported: params.supported, |
| 520 | host_version: params.hostVersion, |
| 521 | unsupported_reason_code: params.unsupportedReasonCode, |
| 522 | host_config_dir_present: params.hostConfigDirPresent, |
| 523 | host_binary_in_known_paths: params.hostBinaryInKnownPaths, |
| 524 | }); |
| 525 | |
| 526 | export const getSetupCancelledEvent = (params: { |
| 527 | readonly operation: 'setup' | 'uninstall'; |
| 528 | readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all'; |
| 529 | readonly invocationOrigin: string; |
| 530 | readonly cliVersion: string; |
| 531 | }): TrackEvent => |
| 532 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_CANCELLED, { |
| 533 | source: 'cli', |
| 534 | invocation_origin: params.invocationOrigin, |
| 535 | cli_version: params.cliVersion, |
| 536 | command_path: 'setup', |
| 537 | operation: params.operation, |
| 538 | requested_target: params.requestedTarget, |
| 539 | reason: 'user_declined', |
| 540 | }); |
| 541 | |
| 542 | export const getSetupSkippedEvent = (params: { |
| 543 | readonly operation: 'setup' | 'uninstall'; |
| 544 | readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all'; |
| 545 | readonly invocationOrigin: string; |
| 546 | readonly cliVersion: string; |
| 547 | }): TrackEvent => |
| 548 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_SETUP_SKIPPED, { |
| 549 | source: 'cli', |
| 550 | invocation_origin: params.invocationOrigin, |
| 551 | cli_version: params.cliVersion, |
| 552 | command_path: 'setup', |
| 553 | operation: params.operation, |
| 554 | requested_target: params.requestedTarget, |
| 555 | reason: 'no_host_detected', |
| 556 | }); |
| 557 | |
| 558 | export const getToolExecuteValidationFailedEvent = (params: { |
| 559 | readonly toolSlug: string; |
| 560 | readonly toolkitSlug?: string; |
| 561 | readonly args: Record<string, unknown>; |
| 562 | readonly error: ToolInputValidationError; |
| 563 | readonly invocationOrigin: string; |
| 564 | readonly surface: 'root' | 'dev'; |
| 565 | readonly projectMode: 'consumer' | 'developer'; |
| 566 | readonly stage: 'dry_run' | 'validation' | 'execution'; |
| 567 | readonly failureOrigin: 'fast_fail' | 'main_endpoint'; |
| 568 | readonly logId?: string; |
| 569 | }): TrackEvent => |
| 570 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_VALIDATION_FAILED, { |
| 571 | source: 'cli', |
| 572 | invocation_origin: params.invocationOrigin, |
| 573 | tool_slug: params.toolSlug, |
| 574 | toolkit_slug: params.toolkitSlug ?? guessToolkitFromToolSlug(params.toolSlug), |
| 575 | surface: params.surface, |
| 576 | project_mode: params.projectMode, |
| 577 | stage: params.stage, |
| 578 | failure_origin: params.failureOrigin, |
| 579 | tool_log_id: params.logId, |
| 580 | issue_count: params.error.issues.length, |
| 581 | issue_locations: extractIssueLocations(params.error.issues), |
| 582 | unknown_keys: extractUnknownKeys(params.error.issues), |
| 583 | schema_path: params.error.schemaPath, |
| 584 | ...argumentShape(params.args), |
| 585 | }); |
| 586 | |
| 587 | export const isMaybeToolNotFoundError = (params: { |
| 588 | readonly message?: string; |
| 589 | readonly errorSlug?: string; |
| 590 | readonly status?: number; |
| 591 | readonly apiCode?: number; |
| 592 | }): boolean => { |
| 593 | if (typeof params.apiCode === 'number' && TOOL_NOT_FOUND_CODES.has(params.apiCode)) return true; |
| 594 | if (params.status === 404) return true; |
| 595 | const errorSlug = params.errorSlug?.toLowerCase() ?? ''; |
| 596 | if (errorSlug.includes('notfound')) return true; |
| 597 | return TOOL_NOT_FOUND_PATTERN.test(params.message ?? ''); |
| 598 | }; |
| 599 | |
| 600 | export const isMaybeToolValidationError = (params: { |
| 601 | readonly message?: string; |
| 602 | readonly errorSlug?: string; |
| 603 | readonly apiCode?: number; |
| 604 | }): boolean => { |
| 605 | if (typeof params.apiCode === 'number' && TOOL_VALIDATION_CODES.has(params.apiCode)) return true; |
| 606 | const errorSlug = params.errorSlug?.toLowerCase() ?? ''; |
| 607 | if (errorSlug.includes('validation') || errorSlug.includes('invalidparameter')) return true; |
| 608 | return TOOL_VALIDATION_PATTERN.test(params.message ?? ''); |
| 609 | }; |
| 610 | |
| 611 | export const getToolExecuteToolNotFoundEvent = (params: { |
| 612 | readonly toolSlug: string; |
| 613 | readonly toolkitSlug?: string; |
| 614 | readonly args: Record<string, unknown>; |
| 615 | readonly invocationOrigin: string; |
| 616 | readonly surface: 'root' | 'dev'; |
| 617 | readonly projectMode: 'consumer' | 'developer'; |
| 618 | readonly stage: 'schema_fetch' | 'dry_run' | 'execution'; |
| 619 | readonly failureOrigin: 'fast_fail' | 'main_endpoint'; |
| 620 | readonly logId?: string; |
| 621 | readonly errorSlug?: string; |
| 622 | readonly status?: number; |
| 623 | readonly apiCode?: number; |
| 624 | readonly message?: string; |
| 625 | }): TrackEvent => |
| 626 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_TOOL_NOT_FOUND, { |
| 627 | source: 'cli', |
| 628 | invocation_origin: params.invocationOrigin, |
| 629 | tool_slug: params.toolSlug, |
| 630 | toolkit_slug: params.toolkitSlug ?? guessToolkitFromToolSlug(params.toolSlug), |
| 631 | surface: params.surface, |
| 632 | project_mode: params.projectMode, |
| 633 | stage: params.stage, |
| 634 | failure_origin: params.failureOrigin, |
| 635 | tool_log_id: params.logId, |
| 636 | error_slug: params.errorSlug, |
| 637 | http_status: params.status, |
| 638 | api_error_code: params.apiCode, |
| 639 | ...argumentShape(params.args), |
| 640 | }); |
| 641 | |
| 642 | export const getToolExecuteFailedEvent = (params: { |
| 643 | readonly toolSlug: string; |
| 644 | readonly toolkitSlug?: string; |
| 645 | readonly args: Record<string, unknown>; |
| 646 | readonly invocationOrigin: string; |
| 647 | readonly surface: 'root' | 'dev'; |
| 648 | readonly projectMode: 'consumer' | 'developer'; |
| 649 | readonly stage: 'schema_fetch' | 'dry_run' | 'execution'; |
| 650 | readonly failureOrigin: 'fast_fail' | 'main_endpoint'; |
| 651 | readonly logId?: string; |
| 652 | readonly errorSlug?: string; |
| 653 | readonly status?: number; |
| 654 | readonly apiCode?: number; |
| 655 | readonly message?: string; |
| 656 | readonly errorName?: string; |
| 657 | readonly isNoConnectionError?: boolean; |
| 658 | }): TrackEvent => |
| 659 | buildEvent(CLI_ANALYTICS_EVENTS.CLI_TOOL_INVOCATION_FAILED, { |
| 660 | source: 'cli', |
| 661 | invocation_origin: params.invocationOrigin, |
| 662 | tool_slug: params.toolSlug, |
| 663 | toolkit_slug: params.toolkitSlug ?? guessToolkitFromToolSlug(params.toolSlug), |
| 664 | surface: params.surface, |
| 665 | project_mode: params.projectMode, |
| 666 | stage: params.stage, |
| 667 | failure_origin: params.failureOrigin, |
| 668 | tool_log_id: params.logId, |
| 669 | error_slug: params.errorSlug, |
| 670 | http_status: params.status, |
| 671 | api_error_code: params.apiCode, |
| 672 | error_name: params.errorName, |
| 673 | is_no_connection_error: Boolean(params.isNoConnectionError), |
| 674 | ...argumentShape(params.args), |
| 675 | }); |