@devries-cameron20 / composio-1 / commits / c4bf563aa
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.

feat(cli): add plugin-adoption telemetry to setup and the plugin hint

Every CLI event now carries agent_host_env (claude, codex, none) read from the host environment. CLI_SETUP_HOST_DETECTED reports whether the host's config dir and a binary at a known install location exist when the host is not detected, CLI_SETUP_FAILED carries a failure_reason_code read from SetupCommandError, and the daily plugin hint emits CLI_PLUGIN_HINT_SHOWN once per printed line and points at `composio setup --yes` so agents no longer run into the non-interactive --yes failure. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Kshitij Jhunjhunwala committed Sep 15, 2026 at 13:19 UTC c4bf563aaa1d2cdb120155d7ee8990088708f236
14 files changed +699 -85
.agents/skills/cli-command/references/implementation.md
+13
@@ -58,6 +58,19 @@ Follow existing local patterns before introducing new service abstractions.
58
59 Never add an `eslint-disable`: `pnpm run validate:boundaries` (CI-blocking via `pnpm test`) rejects any disable not registered in `lint-boundaries.json`. Genuine new runtime boundaries require regenerating the manifest with `pnpm run validate:boundaries -- --update` plus a justification in the PR. Full policy: "Effect Boundary Policy" in `ts/packages/cli/AGENTS.md`.
60
61 +## Analytics Events
62 +
63 +Event names and builders live in `src/analytics/events.ts`; `buildEvent` stamps every event with
64 +`journey_stage`, `cli_channel`, and `agent_host_env` (`claude`, `codex`, or `none`, from
65 +`src/services/agent-host-env.ts`). Setup-related events and their extra properties:
66 +
67 +- `CLI_SETUP_HOST_DETECTED`: `host_config_dir_present` and `host_binary_in_known_paths` only when
68 + `available` is `false` (probed by `src/services/agent-host-locations.ts`).
69 +- `CLI_SETUP_FAILED`: `failure_reason_code` read from `SetupCommandError.reasonCode`
70 + (`src/services/setup-command-error.ts`).
71 +- `CLI_PLUGIN_HINT_SHOWN`: emitted by `src/services/plugin-hint.ts` once per printed hint with
72 + `command_path` and `agent_host`.
73 +
74 ## Required Checks
75
76 For CLI source changes, run from the repo root:
ts/packages/cli/CHANGELOG.md
+6
@@ -4,6 +4,12 @@
4
5 ### Patch Changes
6
7 +- The plugin hint shown under Claude Code or Codex now reads
8 + `'composio setup --yes' installs it`, so an agent following it no longer
9 + fails on the non-interactive `--yes` requirement. CLI telemetry gains
10 + `agent_host_env` on every event, a `CLI_PLUGIN_HINT_SHOWN` event, host
11 + presence signals on `CLI_SETUP_HOST_DETECTED` when a host is not detected,
12 + and a `failure_reason_code` on `CLI_SETUP_FAILED`.
13 - The CLI now runs on Effect 4 (`effect@4.0.0-rc.112`). Unrecognized commands and
14 flags now print a "Did you mean?" suggestion next to the help text for the command
15 that failed to parse, and parse errors for a nested command show that command's
ts/packages/cli/src/analytics/events.ts
+48
@@ -1,7 +1,10 @@
1 import type { CliCommandTelemetryContext, TrackEvent } from './types';
2 import { APP_VERSION } from 'src/constants';
3 import { inferSkillReleaseChannel } from 'src/effects/install-skill';
4 +import type { AgentHost } from 'src/services/agent-host';
5 +import type { AgentHostEnv } from 'src/services/agent-host-env';
6 import type { CliInvocationContext } from 'src/services/runtime-cli-context';
7 +import { setupFailureReasonCodeOf } from 'src/services/setup-command-error';
8 import { ToolInputValidationError } from 'src/services/tool-input-validation';
9 import { guessToolkitFromToolSlug } from 'src/utils/toolkit-from-tool-slug';
10
@@ -42,6 +45,7 @@ export const CLI_ANALYTICS_EVENTS = {
45 CLI_PLUGIN_SETUP_SUCCEEDED: 'CLI_PLUGIN_SETUP_SUCCEEDED',
46 CLI_PLUGIN_SETUP_FAILED: 'CLI_PLUGIN_SETUP_FAILED',
47 CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'CLI_PLUGIN_UNINSTALL_SUCCEEDED',
48 + CLI_PLUGIN_HINT_SHOWN: 'CLI_PLUGIN_HINT_SHOWN',
49 CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'CLI_TOOL_INVOCATION_VALIDATION_FAILED',
50 CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'CLI_TOOL_INVOCATION_TOOL_NOT_FOUND',
51 CLI_TOOL_INVOCATION_FAILED: 'CLI_TOOL_INVOCATION_FAILED',
@@ -97,6 +101,7 @@ export const CLI_EVENT_JOURNEY_STAGES = {
101 CLI_PLUGIN_SETUP_SUCCEEDED: 'setup',
102 CLI_PLUGIN_SETUP_FAILED: 'setup',
103 CLI_PLUGIN_UNINSTALL_SUCCEEDED: 'setup',
104 + CLI_PLUGIN_HINT_SHOWN: 'setup',
105 CLI_TOOL_INVOCATION_VALIDATION_FAILED: 'execute',
106 CLI_TOOL_INVOCATION_TOOL_NOT_FOUND: 'execute',
107 CLI_TOOL_INVOCATION_FAILED: 'execute',
@@ -112,6 +117,12 @@ export const configureCliAnalyticsReleaseVersion = (version: string): void => {
117 cliChannel = inferSkillReleaseChannel(version);
118 };
119
120 +let agentHostEnv: AgentHostEnv = 'none';
121 +
122 +export const configureCliAnalyticsAgentHostEnv = (host: AgentHostEnv): void => {
123 + agentHostEnv = host;
124 +};
125 +
126 const buildEvent = (
127 name: CliAnalyticsEventName,
128 properties: Record<string, unknown>
@@ -121,6 +132,7 @@ const buildEvent = (
132 ...properties,
133 journey_stage: CLI_EVENT_JOURNEY_STAGES[name],
134 cli_channel: cliChannel,
135 + agent_host_env: agentHostEnv,
136 },
137 });
138
@@ -533,8 +545,13 @@ type SpecialLifecycleFamily = {
545 readonly succeededEventName: CliAnalyticsEventName;
546 readonly failedEventName: CliAnalyticsEventName;
547 readonly getProperties: (context: CliCommandTelemetryContext) => Record<string, unknown>;
548 + readonly getFailureProperties?: (error: unknown) => Record<string, unknown>;
549 };
550
551 +const getSetupFailureProperties = (error: unknown) => ({
552 + failure_reason_code: setupFailureReasonCodeOf(error),
553 +});
554 +
555 const SPECIAL_LIFECYCLE_FAMILIES: ReadonlyArray<SpecialLifecycleFamily> = [
556 {
557 match: isExecuteCommand,
@@ -598,6 +615,7 @@ const SPECIAL_LIFECYCLE_FAMILIES: ReadonlyArray<SpecialLifecycleFamily> = [
615 succeededEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_SUCCEEDED,
616 failedEventName: CLI_ANALYTICS_EVENTS.CLI_SETUP_FAILED,
617 getProperties: getSetupCommandProperties,
618 + getFailureProperties: getSetupFailureProperties,
619 },
620 ];
621
@@ -635,9 +653,24 @@ export const getPrimaryLifecycleFailedEvent = (
653 return buildEvent(family.failedEventName, {
654 ...family.getProperties(context),
655 error_name: errorNameOf(error),
656 + ...family.getFailureProperties?.(error),
657 });
658 };
659
660 +export const getPluginHintShownEvent = (params: {
661 + readonly invocationOrigin: string | undefined;
662 + readonly cliVersion: string;
663 + readonly commandPath: string;
664 + readonly agentHost: AgentHost;
665 +}): TrackEvent =>
666 + buildEvent(CLI_ANALYTICS_EVENTS.CLI_PLUGIN_HINT_SHOWN, {
667 + source: 'cli',
668 + invocation_origin: params.invocationOrigin,
669 + cli_version: params.cliVersion,
670 + command_path: params.commandPath,
671 + agent_host: params.agentHost,
672 + });
673 +
674 export const getPluginLifecycleSucceededEvent = (params: {
675 readonly operation: 'setup' | 'uninstall';
676 readonly target: 'claude' | 'codex';
@@ -679,6 +712,18 @@ export const getPluginLifecycleFailedEvent = (params: {
712 error_name: errorNameOf(params.error),
713 });
714
715 +const hostAbsenceProperties = (params: {
716 + readonly available: boolean;
717 + readonly hostConfigDirPresent?: boolean;
718 + readonly hostBinaryInKnownPaths?: boolean;
719 +}) => {
720 + if (params.available) return {};
721 + return {
722 + host_config_dir_present: params.hostConfigDirPresent,
723 + host_binary_in_known_paths: params.hostBinaryInKnownPaths,
724 + };
725 +};
726 +
727 export const getSetupHostDetectedEvent = (params: {
728 readonly operation: 'setup' | 'uninstall';
729 readonly requestedTarget: 'auto' | 'claude' | 'codex' | 'all';
@@ -688,6 +733,8 @@ export const getSetupHostDetectedEvent = (params: {
733 readonly hostVersion?: string;
734 readonly unsupportedReasonCode?:
735 'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown';
736 + readonly hostConfigDirPresent?: boolean;
737 + readonly hostBinaryInKnownPaths?: boolean;
738 readonly invocationOrigin: string;
739 readonly cliVersion: string;
740 }): TrackEvent =>
@@ -703,6 +750,7 @@ export const getSetupHostDetectedEvent = (params: {
750 supported: params.supported,
751 host_version: params.hostVersion,
752 unsupported_reason_code: params.unsupportedReasonCode,
753 + ...hostAbsenceProperties(params),
754 });
755
756 export const getSetupCancelledEvent = (params: {
ts/packages/cli/src/cli-main.ts
+9 -1
@@ -105,8 +105,10 @@ import { ProjectEnvironmentDetector } from 'src/services/project-environment-det
105 import { CommandRunner } from 'src/services/command-runner';
106 import { StdinLive } from 'src/services/stdin';
107 import { showPluginAcquisitionHint } from 'src/services/plugin-hint';
108 +import { agentHostEnvOf, rawHostEnvironment } from 'src/services/agent-host-env';
109 import { showUpdateNotice } from 'src/services/update-check';
110 import {
111 + configureCliAnalyticsAgentHostEnv,
112 configureCliAnalyticsReleaseVersion,
113 createCliCommandTelemetryContext,
114 getExecuteCommandToolSlug,
@@ -310,8 +312,14 @@ export type CliBootstrapOptions = {
312 readonly telemetryDebug: boolean;
313 };
314
315 +// Runs before the plugin hint so that event carries the host too.
316 +const stampAgentHostEnv = rawHostEnvironment.pipe(
317 + Effect.map(env => configureCliAnalyticsAgentHostEnv(agentHostEnvOf(env)))
318 +);
319 +
320 const cliProgram = (argv: ReadonlyArray<string>) =>
314 - showUpdateNotice.pipe(
321 + stampAgentHostEnv.pipe(
322 + Effect.andThen(showUpdateNotice),
323 Effect.andThen(showPluginAcquisitionHint(argv)),
324 Effect.andThen(runWithTelemetry(argv)),
325 Effect.catchIf(
ts/packages/cli/src/commands/setup.cmd.ts
+37 -13
@@ -16,8 +16,10 @@ import {
16 isSetupReady,
17 SETUP_TARGETS,
18 SetupCommandError,
19 + SetupProcessError,
20 uninstallSetupTargets,
21 type AgentHost,
22 + type SetupFailureReasonCode,
23 } from 'src/services/setup';
24 import { TerminalUI } from 'src/services/terminal-ui';
25 import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
@@ -50,13 +52,24 @@ const formatTargets = (targets: ReadonlyArray<AgentHost>): string =>
52 const errorMessage = (error: unknown): string =>
53 Predicate.isError(error) ? error.message : String(error);
54
53 -const setupCommandError = (message: string, operation: 'setup' | 'uninstall', cause?: unknown) =>
55 +const setupCommandError = (
56 + message: string,
57 + operation: 'setup' | 'uninstall',
58 + reasonCode: SetupFailureReasonCode,
59 + cause?: unknown
60 +) =>
61 new SetupCommandError({
62 message,
63 operation,
64 + reasonCode,
65 ...(cause === undefined ? {} : { cause }),
66 });
67
68 +const processFailureReasonCode = (error: unknown): SetupFailureReasonCode => {
69 + if (error instanceof SetupProcessError) return error.reasonCode ?? 'unknown';
70 + return 'unknown';
71 +};
72 +
73 const setupBaseCmd = Command.make(
74 'setup',
75 { target, yes, ifPresent, uninstall },
@@ -82,6 +95,8 @@ const setupBaseCmd = Command.make(
95 detection.available && !detection.supported
96 ? (detection.unsupportedReasonCode ?? 'unknown')
97 : undefined,
98 + hostConfigDirPresent: detection.configDirPresent,
99 + hostBinaryInKnownPaths: detection.binaryInKnownPaths,
100 invocationOrigin,
101 cliVersion: APP_VERSION,
102 })
@@ -103,7 +118,8 @@ const setupBaseCmd = Command.make(
118 if (target === 'all' && notDetected.length > 0) {
119 return yield* setupCommandError(
120 `\`--target all\` requires Claude Code and Codex. Missing: ${formatTargets(notDetected)}. Install the missing agent host, or use \`--target auto\` to operate on detected hosts only.`,
106 - operation
121 + operation,
122 + 'all_requires_both_hosts'
123 );
124 }
125 if (unsupported.length > 0) {
@@ -112,7 +128,7 @@ const setupBaseCmd = Command.make(
128 .filter((message): message is string => Boolean(message))
129 .join(' ');
130 if (target !== 'auto') {
115 - return yield* setupCommandError(reason, operation);
131 + return yield* setupCommandError(reason, operation, 'unsupported_host');
132 }
133 yield* ui.log.warn(
134 `${formatTargets(unsupported.map(result => result.target))} plugin setup skipped. ${reason}`
@@ -132,20 +148,22 @@ const setupBaseCmd = Command.make(
148 );
149 return;
150 }
135 - return yield* setupCommandError(reason, operation);
151 + return yield* setupCommandError(reason, operation, 'unsupported_host');
152 }
153 }
154 if (detected.length === 0) {
155 if (target === 'claude' || target === 'codex') {
156 return yield* setupCommandError(
157 `${target} is not installed or not available on PATH. Install it and rerun \`composio setup${uninstall ? ' --uninstall' : ''} --target ${target}\`.`,
142 - operation
158 + operation,
159 + 'target_not_installed'
160 );
161 }
162 if (!ifPresent || target !== 'auto') {
163 return yield* setupCommandError(
164 `No supported agent host was detected. Install Claude Code or Codex, then rerun \`composio setup${uninstall ? ' --uninstall' : ''}\`.`,
148 - operation
165 + operation,
166 + 'no_host_detected'
167 );
168 }
169 yield* trackCliEventEffect(
@@ -192,7 +210,8 @@ const setupBaseCmd = Command.make(
210 if (!terminal.canPrompt) {
211 return yield* setupCommandError(
212 'Non-interactive uninstall requires `--yes` to approve local changes.',
195 - operation
213 + operation,
214 + 'non_interactive_requires_yes'
215 );
216 }
217 const confirmed = yield* ui.confirm(
@@ -241,7 +260,8 @@ const setupBaseCmd = Command.make(
260 if (!terminal.canPrompt) {
261 return yield* setupCommandError(
262 'Non-interactive setup requires `--yes` to approve local changes.',
244 - operation
263 + operation,
264 + 'non_interactive_requires_yes'
265 );
266 }
267
@@ -285,11 +305,15 @@ const setupBaseCmd = Command.make(
305
306 yield* ui.outro('Composio setup complete.');
307 }).pipe(
288 - Effect.mapError(error =>
289 - error instanceof SetupCommandError
290 - ? error
291 - : setupCommandError(errorMessage(error), uninstall ? 'uninstall' : 'setup', error)
292 - )
308 + Effect.mapError(error => {
309 + if (error instanceof SetupCommandError) return error;
310 + return setupCommandError(
311 + errorMessage(error),
312 + uninstall ? 'uninstall' : 'setup',
313 + processFailureReasonCode(error),
314 + error
315 + );
316 + })
317 )
318 );
319
ts/packages/cli/src/services/agent-host-env.ts new
+64
@@ -0,0 +1,64 @@
1 +import { Config, ConfigProvider, Effect, Option } from 'effect';
2 +import type { AgentHost } from './agent-host';
3 +
4 +export type AgentHostEnv = AgentHost | 'none';
5 +
6 +export interface HostEnvMarkers {
7 + readonly claudeCode: string | undefined;
8 + readonly codexThreadId: string | undefined;
9 + readonly codexSandbox: string | undefined;
10 +}
11 +
12 +export interface RawHostEnvironment extends HostEnvMarkers {
13 + readonly claudeConfigDir: string | undefined;
14 + readonly codexHome: string | undefined;
15 +}
16 +
17 +const isPresent = (value: string | undefined): boolean =>
18 + value !== undefined && value.trim().length > 0;
19 +
20 +const nonBlankOrUndefined = (value: string | undefined): string | undefined => {
21 + if (!isPresent(value)) return undefined;
22 + return value;
23 +};
24 +
25 +export function detectPluginHost(markers: HostEnvMarkers): AgentHost | undefined {
26 + if (isPresent(markers.claudeCode)) return 'claude';
27 + if (isPresent(markers.codexThreadId) || isPresent(markers.codexSandbox)) return 'codex';
28 + return undefined;
29 +}
30 +
31 +export const agentHostEnvOf = (markers: HostEnvMarkers): AgentHostEnv =>
32 + detectPluginHost(markers) ?? 'none';
33 +
34 +const readOptionalEnv = (name: string) =>
35 + Effect.orDie(Config.option(Config.string(name)).pipe(Config.map(Option.getOrUndefined)));
36 +
37 +// Host-owned variables must bypass the CLI ConfigProvider, which prefixes
38 +// application keys with COMPOSIO_. v4's fromEnv() snapshots the environment
39 +// when the provider is built, so it is built per read.
40 +export const rawHostEnvironment: Effect.Effect<RawHostEnvironment> = Effect.gen(function* () {
41 + const claudeCode = yield* readOptionalEnv('CLAUDECODE');
42 + const codexThreadId = yield* readOptionalEnv('CODEX_THREAD_ID');
43 + const codexSandbox = yield* readOptionalEnv('CODEX_SANDBOX');
44 + const claudeConfigDir = nonBlankOrUndefined(yield* readOptionalEnv('CLAUDE_CONFIG_DIR'));
45 + const codexHome = nonBlankOrUndefined(yield* readOptionalEnv('CODEX_HOME'));
46 + return { claudeCode, codexThreadId, codexSandbox, claudeConfigDir, codexHome };
47 +}).pipe(
48 + Effect.provideServiceEffect(
49 + ConfigProvider.ConfigProvider,
50 + Effect.sync(() => ConfigProvider.fromEnv())
51 + )
52 +);
53 +
54 +export const hostConfigDirectory = (params: {
55 + readonly host: AgentHost;
56 + readonly env: RawHostEnvironment;
57 + readonly homedir: string;
58 + readonly join: (...segments: string[]) => string;
59 +}): string => {
60 + if (params.host === 'claude') {
61 + return params.env.claudeConfigDir ?? params.join(params.homedir, '.claude');
62 + }
63 + return params.env.codexHome ?? params.join(params.homedir, '.codex');
64 +};
ts/packages/cli/src/services/agent-host-locations.ts new
+51
@@ -0,0 +1,51 @@
1 +import * as FileSystem from 'effect/FileSystem';
2 +import * as Path from 'effect/Path';
3 +import { Effect } from 'effect';
4 +import type { AgentHost } from './agent-host';
5 +import { hostConfigDirectory, rawHostEnvironment } from './agent-host-env';
6 +import { NodeOs } from './node-os';
7 +
8 +export interface HostInstallationSignals {
9 + readonly configDirPresent: boolean;
10 + readonly binaryInKnownPaths: boolean;
11 +}
12 +
13 +const HOME_RELATIVE_BINARY_DIRS: Readonly<Record<AgentHost, ReadonlyArray<ReadonlyArray<string>>>> =
14 + {
15 + claude: [
16 + ['.claude', 'local'],
17 + ['.local', 'bin'],
18 + ['.npm-global', 'bin'],
19 + ],
20 + codex: [
21 + ['.local', 'bin'],
22 + ['.npm-global', 'bin'],
23 + ],
24 + };
25 +
26 +const ABSOLUTE_BINARY_DIRS = ['/usr/local/bin', '/opt/homebrew/bin'] as const;
27 +
28 +/**
29 + * Cheap on-disk signals that tell a real host absence apart from a PATH miss
30 + * when `<host> --version` cannot be spawned.
31 + */
32 +export const probeHostInstallation = (host: AgentHost) =>
33 + Effect.gen(function* () {
34 + const fs = yield* FileSystem.FileSystem;
35 + const path = yield* Path.Path;
36 + const os = yield* NodeOs;
37 + const env = yield* rawHostEnvironment;
38 + const exists = (target: string) => fs.exists(target).pipe(Effect.orElseSucceed(() => false));
39 +
40 + const configDir = hostConfigDirectory({ host, env, homedir: os.homedir, join: path.join });
41 + const binaries = [
42 + ...HOME_RELATIVE_BINARY_DIRS[host].map(segments => path.join(os.homedir, ...segments, host)),
43 + ...ABSOLUTE_BINARY_DIRS.map(dir => path.join(dir, host)),
44 + ];
45 + const configDirPresent = yield* exists(configDir);
46 + const found = yield* Effect.forEach(binaries, exists);
47 + return {
48 + configDirPresent,
49 + binaryInKnownPaths: found.includes(true),
50 + } satisfies HostInstallationSignals;
51 + });
ts/packages/cli/src/services/plugin-hint.ts
+35 -58
@@ -1,11 +1,15 @@
1 import * as FileSystem from 'effect/FileSystem';
2 import * as Path from 'effect/Path';
3 -import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
4 -import { Config, ConfigProvider, Effect, Layer, Option, Schema } from 'effect';
3 +import { Effect, Option, Schema } from 'effect';
4 +import { trackCliEventEffect } from 'src/analytics/dispatch';
5 +import { getPluginHintShownEvent } from 'src/analytics/events';
6 import { APP_CONFIG } from 'src/effects/app-config';
7 import { setupCacheDir } from 'src/effects/setup-cache-dir';
8 +import { getVersion } from 'src/effects/version';
9 import { AGENT_HOST_LABELS, COMPOSIO_AGENT_PLUGIN_ID, type AgentHost } from './agent-host';
10 +import { detectPluginHost, hostConfigDirectory, rawHostEnvironment } from './agent-host-env';
11 import { NodeOs } from './node-os';
12 +import { cliInvocationContext } from './runtime-cli-context';
13 import { TerminalUI } from './terminal-ui';
14
15 /**
@@ -17,24 +21,6 @@ import { TerminalUI } from './terminal-ui';
21
22 const HINT_INTERVAL_MS = 24 * 60 * 60 * 1000;
23
20 -export interface HostEnvMarkers {
21 - readonly claudeCode: string | undefined;
22 - readonly codexThreadId: string | undefined;
23 - readonly codexSandbox: string | undefined;
24 -}
25 -
26 -const isPresent = (value: string | undefined): boolean =>
27 - value !== undefined && value.trim().length > 0;
28 -
29 -const nonBlankOrUndefined = (value: string | undefined): string | undefined =>
30 - value === undefined || value.trim().length === 0 ? undefined : value;
31 -
32 -export function detectPluginHost(markers: HostEnvMarkers): AgentHost | undefined {
33 - if (isPresent(markers.claudeCode)) return 'claude';
34 - if (isPresent(markers.codexThreadId) || isPresent(markers.codexSandbox)) return 'codex';
35 - return undefined;
36 -}
37 -
24 const InstalledPluginsSchema = Schema.fromJsonString(
25 Schema.Struct({
26 plugins: Schema.Record(Schema.String, Schema.Array(Schema.Unknown)),
@@ -111,6 +97,7 @@ export function createPluginHint(config: PluginHintConfig) {
97 codex: codexPluginAbsent,
98 };
99
100 + /** Resolves to `true` only when the hint line was actually printed. */
101 function showPluginHint(terminal: Pick<TerminalUI, 'error'>) {
102 return Effect.gen(function* () {
103 const host = config.host;
@@ -119,24 +106,20 @@ export function createPluginHint(config: PluginHintConfig) {
106 config.invocationOrigin === 'run' ||
107 config.commandName === 'setup'
108 ) {
122 - return;
109 + return false;
110 }
124 - if (!(yield* pluginAbsentByHost[host])) return;
125 - if (!(yield* claimHint(host))) return;
111 + if (!(yield* pluginAbsentByHost[host])) return false;
112 + if (!(yield* claimHint(host))) return false;
113 yield* terminal.error(
127 - `Tip: running under ${AGENT_HOST_LABELS[host]} without the Composio plugin — 'composio setup' installs it.`
114 + `Tip: running under ${AGENT_HOST_LABELS[host]} without the Composio plugin — 'composio setup --yes' installs it.`
115 );
129 - }).pipe(Effect.ignore);
116 + return true;
117 + }).pipe(Effect.orElseSucceed(() => false));
118 }
119
120 return { showPluginHint };
121 }
122
135 -const DefaultConfigLayers = Layer.mergeAll(Path.layer, NodeOs.Default, BunFileSystem.layer);
136 -
137 -const readOptionalEnv = (name: string) =>
138 - Effect.orDie(Config.option(Config.string(name)).pipe(Config.map(Option.getOrUndefined)));
139 -
123 export function findRootCommandName(argv: ReadonlyArray<string>): string | undefined {
124 const args = argv.slice(2);
125 for (let index = 0; index < args.length; index += 1) {
@@ -153,30 +136,6 @@ export function findRootCommandName(argv: ReadonlyArray<string>): string | undef
136 return undefined;
137 }
138
156 -// Host-owned variables must bypass the CLI ConfigProvider, which prefixes
157 -// application keys with COMPOSIO_.
158 -const rawHostEnvironment = Effect.gen(function* () {
159 - const claudeCode = yield* readOptionalEnv('CLAUDECODE');
160 - const codexThreadId = yield* readOptionalEnv('CODEX_THREAD_ID');
161 - const codexSandbox = yield* readOptionalEnv('CODEX_SANDBOX');
162 - const claudeConfigDir = nonBlankOrUndefined(yield* readOptionalEnv('CLAUDE_CONFIG_DIR'));
163 - const codexHome = nonBlankOrUndefined(yield* readOptionalEnv('CODEX_HOME'));
164 - return {
165 - claudeCode,
166 - codexThreadId,
167 - codexSandbox,
168 - claudeConfigDir,
169 - codexHome,
170 - };
171 -}).pipe(
172 - // v4's fromEnv() snapshots the environment when the provider is built, so
173 - // build it per invocation to keep reading the live host environment.
174 - Effect.provideServiceEffect(
175 - ConfigProvider.ConfigProvider,
176 - Effect.sync(() => ConfigProvider.fromEnv())
177 - )
178 -);
179 -
139 export const resolvePluginHintConfig = (argv: ReadonlyArray<string>) =>
140 Effect.gen(function* () {
141 const path = yield* Path.Path;
@@ -184,25 +143,43 @@ export const resolvePluginHintConfig = (argv: ReadonlyArray<string>) =>
143 const cacheDir = yield* setupCacheDir;
144 const invocationOrigin = yield* APP_CONFIG.CLI_INVOCATION_ORIGIN;
145 const env = yield* rawHostEnvironment;
146 + const configDir = (host: AgentHost) =>
147 + hostConfigDirectory({ host, env, homedir: os.homedir, join: path.join });
148 return {
149 stateDirectory: path.join(cacheDir, 'plugin-hints'),
150 host: detectPluginHost(env),
151 invocationOrigin,
152 commandName: findRootCommandName(argv),
153 claudeInstalledPluginsFile: path.join(
193 - env.claudeConfigDir ?? path.join(os.homedir, '.claude'),
154 + configDir('claude'),
155 'plugins',
156 'installed_plugins.json'
157 ),
197 - codexConfigFile: path.join(env.codexHome ?? path.join(os.homedir, '.codex'), 'config.toml'),
158 + codexConfigFile: path.join(configDir('codex'), 'config.toml'),
159 hintIntervalMs: HINT_INTERVAL_MS,
160 } satisfies PluginHintConfig;
161 });
162
163 +const trackHintShown = (config: PluginHintConfig) =>
164 + Effect.gen(function* () {
165 + if (config.host === undefined) return;
166 + const { invocationOrigin } = yield* cliInvocationContext;
167 + yield* trackCliEventEffect(
168 + getPluginHintShownEvent({
169 + invocationOrigin,
170 + cliVersion: yield* getVersion,
171 + commandPath: config.commandName ?? 'composio',
172 + agentHost: config.host,
173 + })
174 + );
175 + }).pipe(Effect.ignore);
176 +
177 /** Print the plugin acquisition hint when eligible. Never fails, never blocks on network. */
178 export const showPluginAcquisitionHint = (argv: ReadonlyArray<string>) =>
179 Effect.gen(function* () {
180 const terminal = yield* TerminalUI;
181 const config = yield* resolvePluginHintConfig(argv);
207 - yield* createPluginHint(config).showPluginHint(terminal);
208 - }).pipe(Effect.provide(DefaultConfigLayers));
182 + const shown = yield* createPluginHint(config).showPluginHint(terminal);
183 + if (!shown) return;
184 + yield* trackHintShown(config);
185 + });
ts/packages/cli/src/services/setup-command-error.ts new
+22
@@ -0,0 +1,22 @@
1 +import { Data } from 'effect';
2 +
3 +export type SetupFailureReasonCode =
4 + | 'all_requires_both_hosts'
5 + | 'unsupported_host'
6 + | 'target_not_installed'
7 + | 'no_host_detected'
8 + | 'non_interactive_requires_yes'
9 + | 'marketplace_conflict'
10 + | 'unknown';
11 +
12 +export class SetupCommandError extends Data.TaggedError('services/SetupCommandError')<{
13 + readonly message: string;
14 + readonly operation: 'setup' | 'uninstall';
15 + readonly reasonCode: SetupFailureReasonCode;
16 + readonly cause?: unknown;
17 +}> {}
18 +
19 +export const setupFailureReasonCodeOf = (error: unknown): SetupFailureReasonCode => {
20 + if (error instanceof SetupCommandError) return error.reasonCode;
21 + return 'unknown';
22 +};
ts/packages/cli/src/services/setup.ts
+26 -7
@@ -1,3 +1,5 @@
1 +import * as FileSystem from 'effect/FileSystem';
2 +import * as Path from 'effect/Path';
3 import * as PlatformError from 'effect/PlatformError';
4 import { Data, Effect, Option, Predicate, Schema } from 'effect';
5 import { ChildProcess as Command } from 'effect/unstable/process';
@@ -14,8 +16,11 @@ import {
16 COMPOSIO_AGENT_PLUGIN_ID,
17 type AgentHost,
18 } from './agent-host';
19 +import { probeHostInstallation, type HostInstallationSignals } from './agent-host-locations';
20 import { CommandRunner, type CommandResult } from './command-runner';
21 +import { NodeOs } from './node-os';
22 import { SetupSkillInstaller } from './setup-skill-installer';
23 +import type { SetupFailureReasonCode } from './setup-command-error';
24 import { cliInvocationContext } from './runtime-cli-context';
25
26 export const SETUP_TARGETS = ['auto', ...AGENT_HOSTS, 'all'] as const;
@@ -131,11 +136,7 @@ const ADAPTER_LIST = Object.values(ADAPTERS);
136 const SETUP_COMMAND_TIMEOUT = '2 minutes';
137 const MINIMUM_CODEX_SETUP_VERSION = '0.139.0';
138
134 -export class SetupCommandError extends Data.TaggedError('services/SetupCommandError')<{
135 - readonly message: string;
136 - readonly operation: 'setup' | 'uninstall';
137 - readonly cause?: unknown;
138 -}> {}
139 +export { SetupCommandError, type SetupFailureReasonCode } from './setup-command-error';
140
141 type SetupFailureStage = 'detect' | 'inspect' | 'validate' | 'mutate' | 'verify' | 'skill';
142
@@ -143,6 +144,7 @@ export class SetupProcessError extends Data.TaggedError('services/SetupProcessEr
144 readonly message: string;
145 readonly target: AgentHost;
146 readonly stage: SetupFailureStage;
147 + readonly reasonCode?: SetupFailureReasonCode;
148 readonly cause?: unknown;
149 }> {}
150
@@ -150,12 +152,14 @@ const setupProcessError = (params: {
152 readonly adapter: SetupTargetAdapter;
153 readonly stage: SetupFailureStage;
154 readonly message: string;
155 + readonly reasonCode?: SetupFailureReasonCode;
156 readonly cause?: unknown;
157 }) =>
158 new SetupProcessError({
159 message: params.message,
160 target: params.adapter.target,
161 stage: params.stage,
162 + ...(params.reasonCode === undefined ? {} : { reasonCode: params.reasonCode }),
163 ...(params.cause === undefined ? {} : { cause: params.cause }),
164 });
165
@@ -388,11 +392,23 @@ const supportsInspection = (adapter: SetupTargetAdapter, versionOutput?: string)
392 return { supported: true } as const;
393 });
394
395 +type AdapterDetection = Omit<SetupTargetDetection, 'target'>;
396 +
397 +const withInstallationSignals = (
398 + adapter: SetupTargetAdapter,
399 + detection: AdapterDetection
400 +): Effect.Effect<AdapterDetection, never, FileSystem.FileSystem | Path.Path | NodeOs> => {
401 + if (detection.available) return Effect.succeed(detection);
402 + return probeHostInstallation(adapter.target).pipe(
403 + Effect.map(signals => ({ ...detection, ...signals }))
404 + );
405 +};
406 +
407 const detectAdapter = (adapter: SetupTargetAdapter) =>
408 Effect.gen(function* () {
409 const versionArgs = ['--version'];
410 const versionCommand = commandText(adapter.executable, versionArgs);
395 - return yield* captureOptional(adapter, versionArgs).pipe(
411 + const detection = yield* captureOptional(adapter, versionArgs).pipe(
412 Effect.matchEffect({
413 onFailure: cause =>
414 Effect.succeed({
@@ -460,6 +476,7 @@ const detectAdapter = (adapter: SetupTargetAdapter) =>
476 },
477 })
478 );
479 + return yield* withInstallationSignals(adapter, detection);
480 });
481
482 const commandFailureSuffix = (result: CommandResult): string => {
@@ -663,6 +680,7 @@ const validateInitialState = (adapter: SetupTargetAdapter, initial: InspectedSet
680 return setupProcessError({
681 adapter,
682 stage: 'validate',
683 + reasonCode: 'target_not_installed',
684 message: `${adapter.executable} is not installed or not available on PATH. Install it and rerun \`composio setup --target ${adapter.target}\`.`,
685 });
686 }
@@ -670,6 +688,7 @@ const validateInitialState = (adapter: SetupTargetAdapter, initial: InspectedSet
688 return setupProcessError({
689 adapter,
690 stage: 'validate',
691 + reasonCode: 'marketplace_conflict',
692 message: `The ${adapter.target} marketplace named "composio" points to a different source. Run \`${adapter.marketplaceRemoveCommand}\`, then rerun \`composio setup --target ${adapter.target}\`.`,
693 });
694 }
@@ -785,7 +804,7 @@ const FIXED_TARGETS: Readonly<Partial<Record<SetupTarget, ReadonlyArray<AgentHos
804 export type SetupUnsupportedReasonCode =
805 'codex_too_old' | 'no_json_inspection' | 'host_command_failed' | 'unknown';
806
788 -export interface SetupTargetDetection {
807 +export interface SetupTargetDetection extends Partial<HostInstallationSignals> {
808 readonly target: AgentHost;
809 readonly available: boolean;
810 readonly supported: boolean;
ts/packages/cli/test/src/analytics.events.test.ts
+135
@@ -11,8 +11,10 @@ import {
11 CLI_ANALYTICS_EVENTS,
12 CLI_EVENT_JOURNEY_STAGES,
13 CLI_JOURNEY_STAGES,
14 + configureCliAnalyticsAgentHostEnv,
15 configureCliAnalyticsReleaseVersion,
16 createCliCommandTelemetryContext,
17 + getPluginHintShownEvent,
18 getPluginLifecycleFailedEvent,
19 getPluginLifecycleSucceededEvent,
20 getPrimaryLifecycleFailedEvent,
@@ -34,6 +36,7 @@ import {
36 DEFAULT_CLI_INVOCATION_ORIGIN,
37 type CliInvocationContext,
38 } from 'src/services/runtime-cli-context';
39 +import { SetupCommandError } from 'src/services/setup';
40 import { ToolInputValidationError } from 'src/services/tool-input-validation';
41 import { resolveInstalledCliVersion } from 'src/services/run-companion-modules';
42
@@ -305,6 +308,98 @@ describe('CLI analytics setup runtime-context events', () => {
308 });
309 });
310
311 + it('records host presence signals only for an undetected host', () => {
312 + const missing = getSetupHostDetectedEvent({
313 + operation: 'setup',
314 + requestedTarget: 'auto',
315 + target: 'codex',
316 + available: false,
317 + supported: false,
318 + hostConfigDirPresent: true,
319 + hostBinaryInKnownPaths: false,
320 + invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
321 + cliVersion: APP_VERSION,
322 + });
323 + expect(missing?.properties).toMatchObject({
324 + agent_host: 'codex',
325 + available: false,
326 + host_config_dir_present: true,
327 + host_binary_in_known_paths: false,
328 + });
329 +
330 + const detected = getSetupHostDetectedEvent({
331 + operation: 'setup',
332 + requestedTarget: 'auto',
333 + target: 'claude',
334 + available: true,
335 + supported: true,
336 + hostConfigDirPresent: true,
337 + hostBinaryInKnownPaths: true,
338 + invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
339 + cliVersion: APP_VERSION,
340 + });
341 + expect(detected?.properties).not.toHaveProperty('host_config_dir_present');
342 + expect(detected?.properties).not.toHaveProperty('host_binary_in_known_paths');
343 + });
344 +
345 + it('tracks a printed plugin hint as a setup-stage event', () => {
346 + expect(
347 + getPluginHintShownEvent({
348 + invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
349 + cliVersion: APP_VERSION,
350 + commandPath: 'whoami',
351 + agentHost: 'claude',
352 + })
353 + ).toEqual({
354 + name: CLI_ANALYTICS_EVENTS.CLI_PLUGIN_HINT_SHOWN,
355 + properties: {
356 + source: 'cli',
357 + invocation_origin: DEFAULT_CLI_INVOCATION_ORIGIN,
358 + cli_version: APP_VERSION,
359 + command_path: 'whoami',
360 + agent_host: 'claude',
361 + journey_stage: 'setup',
362 + cli_channel: inferSkillReleaseChannel(APP_VERSION),
363 + agent_host_env: 'none',
364 + },
365 + });
366 + });
367 +
368 + it('records the setup failure reason code carried by SetupCommandError', () => {
369 + const context = createCliCommandTelemetryContext(
370 + ['bun', 'composio', 'setup'],
371 + APP_VERSION,
372 + { stdoutIsTTY: false, stderrIsTTY: false },
373 + CLI_INVOCATION
374 + );
375 + const error = new SetupCommandError({
376 + message: 'Non-interactive setup requires `--yes` to approve local changes.',
377 + operation: 'setup',
378 + reasonCode: 'non_interactive_requires_yes',
379 + });
380 +
381 + expect(getPrimaryLifecycleFailedEvent(context, error)?.properties).toMatchObject({
382 + error_name: 'services/SetupCommandError',
383 + failure_reason_code: 'non_interactive_requires_yes',
384 + });
385 + expect(
386 + getPrimaryLifecycleFailedEvent(context, new Error('boom'))?.properties?.failure_reason_code
387 + ).toBe('unknown');
388 + });
389 +
390 + it('keeps failure reason codes out of other lifecycle families', () => {
391 + const context = createCliCommandTelemetryContext(
392 + ['bun', 'composio', 'login'],
393 + APP_VERSION,
394 + { stdoutIsTTY: false, stderrIsTTY: false },
395 + CLI_INVOCATION
396 + );
397 +
398 + expect(
399 + getPrimaryLifecycleFailedEvent(context, new Error('boom'))?.properties
400 + ).not.toHaveProperty('failure_reason_code');
401 + });
402 +
403 it('tracks an unsupported host with a normalized reason code', () => {
404 expect(
405 getSetupHostDetectedEvent({
@@ -391,6 +486,46 @@ describe('CLI analytics setup runtime-context events', () => {
486 });
487 });
488
489 +describe('CLI analytics agent host environment', () => {
490 + afterEach(() => {
491 + configureCliAnalyticsAgentHostEnv('none');
492 + });
493 +
494 + const contextFor = (argv: ReadonlyArray<string>) =>
495 + createCliCommandTelemetryContext(
496 + ['bun', 'composio', ...argv],
497 + APP_VERSION,
498 + { stdoutIsTTY: false, stderrIsTTY: false },
499 + CLI_INVOCATION
500 + );
501 +
502 + it('stamps every event with none until a host is configured', () => {
503 + expect(
504 + getPrimaryLifecycleInvokedEvent(contextFor(['whoami']))?.properties?.agent_host_env
505 + ).toBe('none');
506 + });
507 +
508 + it('stamps lifecycle and standalone events with the configured host', () => {
509 + configureCliAnalyticsAgentHostEnv('codex');
510 +
511 + expect(
512 + getPrimaryLifecycleInvokedEvent(contextFor(['whoami']))?.properties?.agent_host_env
513 + ).toBe('codex');
514 + expect(
515 + getPrimaryLifecycleFailedEvent(contextFor(['setup']), new Error('boom'))?.properties
516 + ?.agent_host_env
517 + ).toBe('codex');
518 + expect(
519 + getSetupSkippedEvent({
520 + operation: 'setup',
521 + requestedTarget: 'auto',
522 + invocationOrigin: DEFAULT_CLI_INVOCATION_ORIGIN,
523 + cliVersion: APP_VERSION,
524 + })?.properties?.agent_host_env
525 + ).toBe('codex');
526 + });
527 +});
528 +
529 describe('CLI analytics journey taxonomy', () => {
530 afterEach(() => {
531 configureCliAnalyticsReleaseVersion(APP_VERSION);
ts/packages/cli/test/src/commands/setup.cmd.test.ts
+92
@@ -1224,3 +1224,95 @@ describe('CLI: composio setup', () => {
1224 );
1225 });
1226 });
1227 +
1228 +const reasonCodeOf = (exit: Exit.Exit<unknown, unknown>): string | undefined => {
1229 + if (!Exit.isFailure(exit)) return undefined;
1230 + const failure = Cause.squash(exit.cause);
1231 + if (failure instanceof SetupCommandError) return failure.reasonCode;
1232 + return undefined;
1233 +};
1234 +
1235 +describe('CLI: composio setup failure reason codes', () => {
1236 + afterEach(() => {
1237 + process.exitCode = undefined;
1238 + });
1239 +
1240 + const claudeOnly = makeFakeHosts({ claude: { available: true } });
1241 + layer(TestLive({ commandRunner: claudeOnly.runner }))('only Claude Code installed', it => {
1242 + it.effect('codes `--target all` with a missing host', () =>
1243 + Effect.gen(function* () {
1244 + const exit = yield* Effect.exit(cli(['setup', '--target', 'all', '--yes']));
1245 + expect(reasonCodeOf(exit)).toBe('all_requires_both_hosts');
1246 + })
1247 + );
1248 +
1249 + it.effect('codes an explicitly requested missing host', () =>
1250 + Effect.gen(function* () {
1251 + const exit = yield* Effect.exit(cli(['setup', '--target', 'codex', '--yes']));
1252 + expect(reasonCodeOf(exit)).toBe('target_not_installed');
1253 + })
1254 + );
1255 +
1256 + it.effect('codes a non-interactive run without --yes', () =>
1257 + Effect.gen(function* () {
1258 + const exit = yield* Effect.exit(cli(['setup', '--target', 'claude']));
1259 + expect(reasonCodeOf(exit)).toBe('non_interactive_requires_yes');
1260 + })
1261 + );
1262 + });
1263 +
1264 + const noHosts = makeFakeHosts({});
1265 + layer(TestLive({ commandRunner: noHosts.runner }))('no host installed', it => {
1266 + it.effect('codes automatic detection that finds nothing', () =>
1267 + Effect.gen(function* () {
1268 + const exit = yield* Effect.exit(cli(['setup', '--yes']));
1269 + expect(reasonCodeOf(exit)).toBe('no_host_detected');
1270 + })
1271 + );
1272 + });
1273 +
1274 + const legacyCodex = makeFakeHosts(
1275 + { codex: { available: true } },
1276 + { codexVersion: 'codex-cli 0.137.0' }
1277 + );
1278 + layer(TestLive({ commandRunner: legacyCodex.runner }))('unsupported Codex only', it => {
1279 + it.effect('codes an unsupported explicit target', () =>
1280 + Effect.gen(function* () {
1281 + const exit = yield* Effect.exit(cli(['setup', '--target', 'codex', '--yes']));
1282 + expect(reasonCodeOf(exit)).toBe('unsupported_host');
1283 + })
1284 + );
1285 +
1286 + it.effect('codes automatic detection that only finds unsupported hosts', () =>
1287 + Effect.gen(function* () {
1288 + const exit = yield* Effect.exit(cli(['setup', '--yes']));
1289 + expect(reasonCodeOf(exit)).toBe('unsupported_host');
1290 + })
1291 + );
1292 + });
1293 +
1294 + const conflict = makeFakeHosts({ claude: { available: true, marketplace: 'conflict' } });
1295 + layer(TestLive({ commandRunner: conflict.runner }))('marketplace conflict', it => {
1296 + it.effect('codes the conflicting marketplace', () =>
1297 + Effect.gen(function* () {
1298 + const exit = yield* Effect.exit(cli(['setup', '--target', 'claude', '--yes']));
1299 + expect(reasonCodeOf(exit)).toBe('marketplace_conflict');
1300 + })
1301 + );
1302 + });
1303 +
1304 + const failedInstall = makeFakeHosts(
1305 + { claude: { available: true } },
1306 + { failOn: 'plugin install' }
1307 + );
1308 + layer(
1309 + TestLive({ commandRunner: failedInstall.runner, setupSkillInstaller: makeSkillInstaller() })
1310 + )('native install failure', it => {
1311 + it.effect('codes every other failure as unknown', () =>
1312 + Effect.gen(function* () {
1313 + const exit = yield* Effect.exit(cli(['setup', '--target', 'claude', '--yes']));
1314 + expect(reasonCodeOf(exit)).toBe('unknown');
1315 + })
1316 + );
1317 + });
1318 +});
ts/packages/cli/test/src/commands/setup.telemetry.cmd.test.ts
+55
@@ -1,8 +1,11 @@
1 +import { mkdirSync, writeFileSync } from 'node:fs';
2 +import { join } from 'node:path';
3 import { describe, expect, layer } from '@effect/vitest';
4 import { Effect, Exit } from 'effect';
5 import { ChildProcess, ChildProcessSpawner } from 'effect/unstable/process';
6 import { afterEach, beforeEach, vi } from 'vitest';
7 import { CommandRunner } from 'src/services/command-runner';
8 +import { NodeOs } from 'src/services/node-os';
9 import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
10 import { getTerminalCapabilities, TerminalUI } from 'src/services/terminal-ui';
11 import { cli, TestLive } from 'test/__utils__';
@@ -180,9 +183,42 @@ describe('CLI: composio setup telemetry', () => {
183 });
184
185 afterEach(() => {
186 + vi.unstubAllEnvs();
187 process.exitCode = undefined;
188 });
189
190 + const hostSignals = makeFakeHosts({ claude: { available: true } });
191 + layer(
192 + TestLive({
193 + commandRunner: hostSignals.runner,
194 + setupSkillInstaller: makeSkillInstaller(),
195 + })
196 + )('undetected host presence signals', it => {
197 + it.effect('reports the config dir and known binary paths only for the undetected host', () =>
198 + Effect.gen(function* () {
199 + vi.stubEnv('CODEX_HOME', '');
200 + const os = yield* NodeOs;
201 + mkdirSync(join(os.homedir, '.codex'), { recursive: true });
202 + mkdirSync(join(os.homedir, '.local', 'bin'), { recursive: true });
203 + writeFileSync(join(os.homedir, '.local', 'bin', 'codex'), '');
204 +
205 + yield* cli(['setup', '--target', 'auto', '--yes']);
206 +
207 + const detected = eventsNamed('CLI_SETUP_HOST_DETECTED');
208 + const codex = detected.find(event => event.properties?.agent_host === 'codex');
209 + const claude = detected.find(event => event.properties?.agent_host === 'claude');
210 + expect(codex?.properties).toMatchObject({
211 + available: false,
212 + host_config_dir_present: true,
213 + host_binary_in_known_paths: true,
214 + });
215 + expect(claude?.properties).toMatchObject({ available: true });
216 + expect(claude?.properties).not.toHaveProperty('host_config_dir_present');
217 + expect(claude?.properties).not.toHaveProperty('host_binary_in_known_paths');
218 + })
219 + );
220 + });
221 +
222 const freshClaude = makeFakeHosts({ claude: { available: true } });
223 layer(
224 TestLive({
@@ -285,6 +321,25 @@ describe('CLI: composio setup telemetry', () => {
321 expect(eventsNamed('CLI_SETUP_CANCELLED')).toHaveLength(0);
322 })
323 );
324 +
325 + it.effect('reports absent config dirs for every undetected host', () =>
326 + Effect.gen(function* () {
327 + vi.stubEnv('CLAUDE_CONFIG_DIR', '');
328 + vi.stubEnv('CODEX_HOME', '');
329 +
330 + yield* cli(['setup', '--target', 'auto', '--yes', '--if-present']);
331 +
332 + const detected = eventsNamed('CLI_SETUP_HOST_DETECTED');
333 + expect(detected).toHaveLength(2);
334 + for (const event of detected) {
335 + expect(event.properties).toMatchObject({
336 + available: false,
337 + host_config_dir_present: false,
338 + host_binary_in_known_paths: expect.any(Boolean),
339 + });
340 + }
341 + })
342 + );
343 });
344
345 const declinedSetup = makeFakeHosts({ claude: { available: true } });
ts/packages/cli/test/src/services/plugin-hint.test.ts
+106 -6
@@ -1,6 +1,8 @@
1 -import { afterEach, beforeEach, describe, expect, it, vi } from '@effect/vitest';
1 +import { describe, expect, it } from '@effect/vitest';
2 +import { afterEach, beforeEach, vi } from 'vitest';
3 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
4 import * as BunPath from '@effect/platform-bun/BunPath';
5 +import * as BunServices from '@effect/platform-bun/BunServices';
6 import { ConfigProvider, Effect, Layer } from 'effect';
7 import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
8 import { tmpdir } from 'node:os';
@@ -8,14 +10,35 @@ import { dirname, join } from 'node:path';
10 import { Writable } from 'node:stream';
11 import { extendConfigProvider } from 'src/services/config';
12 import { defaultNodeOs, NodeOs } from 'src/services/node-os';
13 +import { NodeProcess } from 'src/services/node-process';
14 +import { detectPluginHost } from 'src/services/agent-host-env';
15 import {
16 createPluginHint,
13 - detectPluginHost,
17 findRootCommandName,
18 resolvePluginHintConfig,
19 + showPluginAcquisitionHint,
20 type PluginHintConfig,
21 } from 'src/services/plugin-hint';
18 -import { makeTerminalUI, type TerminalUI } from 'src/services/terminal-ui';
22 +import { makeTerminalUI, TerminalUI } from 'src/services/terminal-ui';
23 +import { terminalUITestImpl } from 'test/__utils__/services/terminal-ui-test';
24 +
25 +const tracked = vi.hoisted(() => ({
26 + events: [] as Array<{ readonly name: string; readonly properties?: Record<string, unknown> }>,
27 +}));
28 +
29 +vi.mock('src/analytics/dispatch', async importOriginal => {
30 + const actual = await importOriginal<typeof import('src/analytics/dispatch')>();
31 + const { Effect } = await import('effect');
32 + return {
33 + ...actual,
34 + trackCliEventEffect: (
35 + event: { readonly name: string; readonly properties?: Record<string, unknown> } | null
36 + ) =>
37 + Effect.sync(() => {
38 + if (event) tracked.events.push(event);
39 + }),
40 + };
41 +});
42
43 const DAY_MS = 24 * 60 * 60 * 1000;
44
@@ -26,6 +49,7 @@ beforeEach(() => {
49 afterEach(() => {
50 vi.useRealTimers();
51 vi.unstubAllEnvs();
52 + tracked.events.length = 0;
53 rmSync(tempDir, { recursive: true, force: true });
54 });
55
@@ -186,9 +210,23 @@ describe('showPluginHint', () => {
210 writeFileAt(codexConfig.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
211 yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
212
189 - expect(output).toHaveLength(2);
190 - expect(output[0]).toContain('Claude Code');
191 - expect(output[1]).toContain('Codex');
213 + expect(output).toEqual([
214 + "Tip: running under Claude Code without the Composio plugin — 'composio setup --yes' installs it.",
215 + "Tip: running under Codex without the Composio plugin — 'composio setup --yes' installs it.",
216 + ]);
217 + }).pipe(Effect.provide(PlatformLayers))
218 + );
219 +
220 + it.effect('reports whether the hint was printed', () =>
221 + Effect.gen(function* () {
222 + const config = makeConfig();
223 +
224 + const first = yield* createPluginHint(config).showPluginHint(makeTerminal(output));
225 + const second = yield* createPluginHint(config).showPluginHint(makeTerminal(output));
226 +
227 + expect(first).toBe(true);
228 + expect(second).toBe(false);
229 + expect(output).toHaveLength(1);
230 }).pipe(Effect.provide(PlatformLayers))
231 );
232
@@ -303,3 +341,65 @@ describe('showPluginHint', () => {
341 }).pipe(Effect.provide(PlatformLayers))
342 );
343 });
344 +
345 +describe('showPluginAcquisitionHint', () => {
346 + const output: string[] = [];
347 + const runHint = (argv: ReadonlyArray<string>) =>
348 + showPluginAcquisitionHint(argv).pipe(
349 + Effect.provideService(
350 + ConfigProvider.ConfigProvider,
351 + extendConfigProvider(ConfigProvider.fromEnv())
352 + ),
353 + Effect.provide(
354 + Layer.mergeAll(
355 + BunServices.layer,
356 + NodeProcess.Default,
357 + Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })),
358 + Layer.succeed(
359 + TerminalUI,
360 + TerminalUI.of({
361 + ...terminalUITestImpl,
362 + error: line => Effect.sync(() => output.push(line)),
363 + })
364 + )
365 + )
366 + )
367 + );
368 +
369 + beforeEach(() => {
370 + output.length = 0;
371 + vi.stubEnv('COMPOSIO_CACHE_DIR', join(tempDir, 'cache'));
372 + vi.stubEnv('CLAUDECODE', '1');
373 + vi.stubEnv('COMPOSIO_CLI_INVOCATION_ORIGIN', 'installer');
374 + });
375 +
376 + it.effect('tracks CLI_PLUGIN_HINT_SHOWN once per printed hint', () =>
377 + Effect.gen(function* () {
378 + yield* runHint(['/bin/bun', '/cli/bin.ts', 'whoami']);
379 + yield* runHint(['/bin/bun', '/cli/bin.ts', 'whoami']);
380 +
381 + expect(output).toHaveLength(1);
382 + expect(tracked.events).toEqual([
383 + {
384 + name: 'CLI_PLUGIN_HINT_SHOWN',
385 + properties: expect.objectContaining({
386 + source: 'cli',
387 + invocation_origin: 'installer',
388 + cli_version: expect.any(String),
389 + command_path: 'whoami',
390 + agent_host: 'claude',
391 + }),
392 + },
393 + ]);
394 + })
395 + );
396 +
397 + it.effect('tracks nothing when the hint is suppressed', () =>
398 + Effect.gen(function* () {
399 + yield* runHint(['/bin/bun', '/cli/bin.ts', 'setup']);
400 +
401 + expect(output).toEqual([]);
402 + expect(tracked.events).toEqual([]);
403 + })
404 + );
405 +});