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
+});