@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 04:45 UTC

next
ts 675 lines 24.1 KB
Raw
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 });