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

fix(cli): simplify and harden plugin hints

Kshitij Jhunjhunwala committed Jul 29, 2026 at 18:05 UTC af772565f7fc34cf1eb9a1109ef7c4ac1294fe8d
7 files changed +218 -313
mise.lock
+8 -12
@@ -89,23 +89,23 @@ version = "3.12.13"
89 backend = "core:python"
90
91 [tools.python."platforms.linux-arm64"]
92 -checksum = "sha256:e125d3e75034fe75d49ae8577b53758b0bb7d7817fadde2c020ad2cf7afe64c4"
93 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260728/cpython-3.12.13+20260728-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"
92 +checksum = "sha256:f226576b91491ffa5739aa85726521e9031f4d87f80627d64ed348ac77cb31e9"
93 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-unknown-linux-gnu-install_only_stripped.tar.gz"
94 provenance = "github-attestations"
95
96 [tools.python."platforms.linux-x64"]
97 -checksum = "sha256:7ceaf4360f4b4ab44f31d8217cfdc70df8e12b61d9561b4900ee7af87176e50d"
98 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260728/cpython-3.12.13+20260728-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"
97 +checksum = "sha256:5854aa6ec71cad00334d5065633c210b2e7feb40956767a59a91791cadcf0b79"
98 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-unknown-linux-gnu-install_only_stripped.tar.gz"
99 provenance = "github-attestations"
100
101 [tools.python."platforms.macos-arm64"]
102 -checksum = "sha256:2f18cdef4125ca1440dd1ba00ebcb267526efb532138c0860438f755ea4eebac"
103 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260728/cpython-3.12.13+20260728-aarch64-apple-darwin-install_only_stripped.tar.gz"
102 +checksum = "sha256:9a1e9e06175c10efd8378b904b07fa21bd791ab3345d7cdffeb4a76c9ff55903"
103 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-aarch64-apple-darwin-install_only_stripped.tar.gz"
104 provenance = "github-attestations"
105
106 [tools.python."platforms.macos-x64"]
107 -checksum = "sha256:e654c21d0ba53e2c671868d4112fac5874deca4c35226d36c5cfe53bc5c9cd71"
108 -url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260728/cpython-3.12.13+20260728-x86_64-apple-darwin-install_only_stripped.tar.gz"
107 +checksum = "sha256:8e6b7e6533bdf746287008edf91102e7bee0a6ca1d24f16c4514237cafd706c5"
108 +url = "https://github.com/astral-sh/python-build-standalone/releases/download/20260718/cpython-3.12.13+20260718-x86_64-apple-darwin-install_only_stripped.tar.gz"
109 provenance = "github-attestations"
110
111 [[tools.uv]]
@@ -115,19 +115,15 @@ backend = "aqua:astral-sh/uv"
115 [tools.uv."platforms.linux-arm64"]
116 checksum = "sha256:87925376fa1e59de23582e1cbd81d6aabd16611e871ad085e09be2c2fa12689d"
117 url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-aarch64-unknown-linux-musl.tar.gz"
118 -url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160192"
118
119 [tools.uv."platforms.linux-x64"]
120 checksum = "sha256:6a37f712ae90c7b8cf364fe751144d7acc2479d6b336378111e74cc7fb14fa7b"
121 url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-x86_64-unknown-linux-musl.tar.gz"
123 -url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160235"
122
123 [tools.uv."platforms.macos-arm64"]
124 checksum = "sha256:bb63d43c40a301d889a985223ee8ce540be199e98b3f27ed8477823869a0a605"
125 url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-aarch64-apple-darwin.tar.gz"
128 -url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160180"
126
127 [tools.uv."platforms.macos-x64"]
128 checksum = "sha256:b5f91770e55761b32c9618757ef23ded6671bb9ca0ddf5737eea60dddd493fe9"
129 url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-x86_64-apple-darwin.tar.gz"
133 -url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160227"
ts/packages/cli/src/cli-main.ts
+1 -1
@@ -175,7 +175,7 @@ const runWithTelemetry = Effect.gen(function* () {
175 });
176
177 showUpdateNotice.pipe(
178 - Effect.andThen(showPluginAcquisitionHint),
178 + Effect.andThen(showPluginAcquisitionHint(process.argv)),
179 Effect.andThen(runWithTelemetry),
180 Effect.catchIf(ValidationError.isValidationError, error => {
181 return Effect.gen(function* () {
ts/packages/cli/src/commands/setup.cmd.ts
+7 -11
@@ -7,6 +7,7 @@ import {
7 getSetupSkippedEvent,
8 } from 'src/analytics/events';
9 import { APP_VERSION } from 'src/constants';
10 +import { AGENT_HOST_LABELS } from 'src/services/agent-host';
11 import {
12 detectSetupTargets,
13 inspectSetupTargets,
@@ -42,13 +43,8 @@ const uninstall = Options.boolean('uninstall').pipe(
43 Options.withDescription('Uninstall Composio plugins instead of installing them')
44 );
45
45 -const TARGET_LABELS: Readonly<Record<AgentHost, string>> = {
46 - claude: 'Claude Code',
47 - codex: 'Codex',
48 -};
49 -
46 const formatTargets = (targets: ReadonlyArray<AgentHost>): string =>
51 - targets.map(target => TARGET_LABELS[target]).join(' and ');
47 + targets.map(target => AGENT_HOST_LABELS[target]).join(' and ');
48
49 const errorMessage = (error: unknown): string =>
50 Predicate.isError(error) ? error.message : String(error);
@@ -170,12 +166,12 @@ const setupBaseCmd = Command.make(
166
167 for (const status of installed) {
168 yield* ui.log.success(
173 - `The Composio plugin for ${TARGET_LABELS[status.target]} is installed.`
169 + `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is installed.`
170 );
171 }
172 for (const status of notInstalled) {
173 yield* ui.log.info(
178 - `The Composio plugin for ${TARGET_LABELS[status.target]} is not installed.`
174 + `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is not installed.`
175 );
176 }
177
@@ -207,7 +203,7 @@ const setupBaseCmd = Command.make(
203 for (const result of results) {
204 if (!result.plugin_changed) continue;
205 yield* ui.log.success(
210 - `Successfully uninstalled the Composio plugin for ${TARGET_LABELS[result.target]}.`
206 + `Successfully uninstalled the Composio plugin for ${AGENT_HOST_LABELS[result.target]}.`
207 );
208 }
209 yield* ui.outro('Composio plugin uninstall complete.');
@@ -216,7 +212,7 @@ const setupBaseCmd = Command.make(
212
213 for (const status of inspected.filter(isSetupPluginReady)) {
214 yield* ui.log.success(
219 - `The Composio plugin for ${TARGET_LABELS[status.target]} is already installed and enabled.`
215 + `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is already installed and enabled.`
216 );
217 }
218
@@ -267,7 +263,7 @@ const setupBaseCmd = Command.make(
263 if (!initial.plugin_installed) action = 'installed and enabled';
264 else if (!initial.plugin_enabled) action = 'enabled';
265 yield* ui.log.success(
270 - `Successfully ${action} the Composio plugin for ${TARGET_LABELS[result.target]}.`
266 + `Successfully ${action} the Composio plugin for ${AGENT_HOST_LABELS[result.target]}.`
267 );
268 }
269
ts/packages/cli/src/services/agent-host.ts new
+10
@@ -0,0 +1,10 @@
1 +export const AGENT_HOSTS = ['claude', 'codex'] as const;
2 +
3 +export type AgentHost = (typeof AGENT_HOSTS)[number];
4 +
5 +export const AGENT_HOST_LABELS: Readonly<Record<AgentHost, string>> = {
6 + claude: 'Claude Code',
7 + codex: 'Codex',
8 +};
9 +
10 +export const COMPOSIO_AGENT_PLUGIN_ID = 'composio@composio';
ts/packages/cli/src/services/plugin-hint.ts
+96 -138
@@ -1,28 +1,19 @@
1 import { FileSystem, Path } from '@effect/platform';
2 import { BunFileSystem } from '@effect/platform-bun';
3 import { Config, ConfigProvider, Effect, Layer, Option, Schema } from 'effect';
4 +import { setupCacheDir } from 'src/effects/setup-cache-dir';
5 +import { AGENT_HOST_LABELS, COMPOSIO_AGENT_PLUGIN_ID, type AgentHost } from './agent-host';
6 import { NodeOs } from './node-os';
7 import { TerminalUI } from './terminal-ui';
8
9 /**
10 * One-line acquisition hint for the Composio agent plugin.
11 *
10 - * When the bare CLI runs inside a plugin-capable agent host (Claude Code,
11 - * Codex) and the Composio plugin is not installed there, print one throttled
12 - * tip to stderr. The primary audience is the agent driving the CLI through a
13 - * non-TTY shell, so unlike the rest of the CLI's decoration this line is NOT
14 - * gated on stderr being a TTY.
12 + * The primary audience is the agent driving the CLI through a non-TTY shell,
13 + * so this line is intentionally not gated on stderr being a TTY.
14 */
15
16 const HINT_INTERVAL_MS = 24 * 60 * 60 * 1000;
18 -const PLUGIN_ID = 'composio@composio';
19 -
20 -export type PluginHost = 'claude' | 'codex';
21 -
22 -const HOST_LABELS: Record<PluginHost, string> = {
23 - claude: 'Claude Code',
24 - codex: 'Codex',
25 -};
17
18 export interface HostEnvMarkers {
19 readonly claudeCode: string | undefined;
@@ -30,63 +21,15 @@ export interface HostEnvMarkers {
21 readonly codexSandbox: string | undefined;
22 }
23
33 -export function detectPluginHost(markers: HostEnvMarkers): PluginHost | undefined {
34 - if (markers.claudeCode !== undefined) return 'claude';
35 - if (markers.codexThreadId !== undefined || markers.codexSandbox !== undefined) return 'codex';
36 - return undefined;
37 -}
24 +const isPresent = (value: string | undefined): boolean =>
25 + value !== undefined && value.trim().length > 0;
26
39 -export interface PluginHintState {
40 - readonly lastHintShown: {
41 - readonly claude?: string; // ISO-8601
42 - readonly codex?: string; // ISO-8601
43 - };
27 +export function detectPluginHost(markers: HostEnvMarkers): AgentHost | undefined {
28 + if (isPresent(markers.claudeCode)) return 'claude';
29 + if (isPresent(markers.codexThreadId) || isPresent(markers.codexSandbox)) return 'codex';
30 + return undefined;
31 }
32
46 -const CurrentPluginHintStateSchema = Schema.Struct({
47 - lastHintShown: Schema.Struct({
48 - claude: Schema.optional(Schema.String),
49 - codex: Schema.optional(Schema.String),
50 - }),
51 -});
52 -
53 -const LegacyPluginHintStateSchema = Schema.Struct({
54 - lastHintShown: Schema.String,
55 -});
56 -
57 -const PluginHintStateSchema = Schema.parseJson(
58 - Schema.Union(CurrentPluginHintStateSchema, LegacyPluginHintStateSchema)
59 -);
60 -
61 -const normalizePluginHintState = (
62 - state:
63 - | Schema.Schema.Type<typeof CurrentPluginHintStateSchema>
64 - | {
65 - readonly lastHintShown: string;
66 - }
67 -): PluginHintState => {
68 - const lastHintShown = state.lastHintShown;
69 - if (typeof lastHintShown === 'string') {
70 - return {
71 - // Preserve the legacy global throttle during migration.
72 - lastHintShown: {
73 - claude: lastHintShown,
74 - codex: lastHintShown,
75 - },
76 - };
77 - }
78 - return { lastHintShown };
79 -};
80 -
81 -const PluginHintStateOutputSchema = Schema.parseJson(
82 - Schema.Struct({
83 - lastHintShown: Schema.Struct({
84 - claude: Schema.optional(Schema.String),
85 - codex: Schema.optional(Schema.String),
86 - }),
87 - })
88 -);
89 -
33 const InstalledPluginsSchema = Schema.parseJson(
34 Schema.Struct({
35 plugins: Schema.Record({ key: Schema.String, value: Schema.Array(Schema.Unknown) }),
@@ -94,73 +37,70 @@ const InstalledPluginsSchema = Schema.parseJson(
37 );
38
39 export interface PluginHintConfig {
97 - readonly stateFile: string;
98 - readonly host: PluginHost | undefined;
40 + readonly stateDirectory: string;
41 + readonly host: AgentHost | undefined;
42 readonly invocationOrigin: string | undefined;
43 + readonly commandName: string | undefined;
44 readonly claudeInstalledPluginsFile: string;
45 readonly codexConfigFile: string;
46 readonly hintIntervalMs: number;
47 }
48
49 export function createPluginHint(config: PluginHintConfig) {
106 - const readState = Effect.gen(function* () {
107 - const fs = yield* FileSystem.FileSystem;
108 - const rawState = yield* fs.readFileString(config.stateFile);
109 - return normalizePluginHintState(yield* Schema.decodeUnknown(PluginHintStateSchema)(rawState));
110 - });
111 -
112 - const writeState = (host: PluginHost, previous: Option.Option<PluginHintState>) =>
50 + const claimHint = (host: AgentHost) =>
51 Effect.gen(function* () {
52 const fs = yield* FileSystem.FileSystem;
53 const path = yield* Path.Path;
116 - const state: PluginHintState = {
117 - lastHintShown: {
118 - ...(Option.isSome(previous) ? previous.value.lastHintShown : {}),
119 - [host]: new Date().toISOString(),
120 - },
121 - };
122 - const encoded = yield* Schema.encode(PluginHintStateOutputSchema)(state);
123 - yield* fs.makeDirectory(path.dirname(config.stateFile), { recursive: true });
124 - yield* fs.writeFileString(config.stateFile, encoded);
125 - });
126 -
127 - const shownWithinInterval = (
128 - state: Option.Option<PluginHintState>,
129 - host: PluginHost
130 - ): boolean => {
131 - if (Option.isNone(state)) return false;
132 - const lastHintShown = state.value.lastHintShown[host];
133 - if (lastHintShown === undefined) return false;
134 - const shownAt = new Date(lastHintShown).getTime();
135 - if (!Number.isFinite(shownAt)) return false;
136 - return Date.now() - shownAt < config.hintIntervalMs;
137 - };
54 + const stampPath = path.join(config.stateDirectory, `${host}.stamp`);
55 + yield* fs.makeDirectory(config.stateDirectory, { recursive: true });
56 +
57 + const stampInfo = yield* Effect.option(fs.stat(stampPath));
58 + if (Option.isSome(stampInfo)) {
59 + const shownAt = Option.getOrUndefined(stampInfo.value.mtime)?.getTime();
60 + if (
61 + shownAt !== undefined &&
62 + Number.isFinite(shownAt) &&
63 + Date.now() - shownAt < config.hintIntervalMs
64 + ) {
65 + return false;
66 + }
67 +
68 + // Retiring via rename means only one concurrent process can replace a
69 + // stale stamp. Everyone else either sees the new stamp or loses the
70 + // exclusive create below.
71 + const retiredPath = `${stampPath}.${crypto.randomUUID()}`;
72 + const retired = yield* Effect.option(fs.rename(stampPath, retiredPath));
73 + yield* fs.remove(retiredPath, { force: true }).pipe(Effect.ignore);
74 + if (Option.isNone(retired)) return false;
75 + }
76 +
77 + return yield* Effect.scoped(fs.open(stampPath, { flag: 'wx' })).pipe(
78 + Effect.as(true),
79 + Effect.orElseSucceed(() => false)
80 + );
81 + }).pipe(Effect.orElseSucceed(() => false));
82
83 // "Confidently absent" only: a missing state file means the plugin was never
84 // installed, while an unreadable or unrecognized one suppresses the hint.
85 const claudePluginAbsent = Effect.gen(function* () {
86 const fs = yield* FileSystem.FileSystem;
143 - const fileExists = yield* fs.exists(config.claudeInstalledPluginsFile);
144 - if (!fileExists) return true;
87 + if (!(yield* fs.exists(config.claudeInstalledPluginsFile))) return true;
88 const raw = yield* fs.readFileString(config.claudeInstalledPluginsFile);
89 const decoded = yield* Effect.option(Schema.decodeUnknown(InstalledPluginsSchema)(raw));
90 if (Option.isNone(decoded)) return false;
148 - const installs = decoded.value.plugins[PLUGIN_ID];
149 - if (installs === undefined) return true;
150 - return installs.length === 0;
91 + const installs = decoded.value.plugins[COMPOSIO_AGENT_PLUGIN_ID];
92 + return installs === undefined || installs.length === 0;
93 });
94
95 const codexPluginAbsent = Effect.gen(function* () {
96 const fs = yield* FileSystem.FileSystem;
155 - const fileExists = yield* fs.exists(config.codexConfigFile);
156 - if (!fileExists) return true;
97 + if (!(yield* fs.exists(config.codexConfigFile))) return true;
98 const raw = yield* fs.readFileString(config.codexConfigFile);
158 - return !raw.includes(`[plugins."${PLUGIN_ID}"]`);
99 + return !raw.includes(`[plugins."${COMPOSIO_AGENT_PLUGIN_ID}"]`);
100 });
101
161 - const pluginAbsentByHost: Record<
162 - PluginHost,
163 - Effect.Effect<boolean, unknown, FileSystem.FileSystem>
102 + const pluginAbsentByHost: Readonly<
103 + Record<AgentHost, Effect.Effect<boolean, unknown, FileSystem.FileSystem>>
104 > = {
105 claude: claudePluginAbsent,
106 codex: codexPluginAbsent,
@@ -168,16 +108,18 @@ export function createPluginHint(config: PluginHintConfig) {
108
109 function showPluginHint(terminal: Pick<TerminalUI, 'error'>) {
110 return Effect.gen(function* () {
171 - if (config.host === undefined) return;
172 - if (config.invocationOrigin === 'run') return;
173 - const state = yield* Effect.option(readState);
174 - if (shownWithinInterval(state, config.host)) return;
175 - const absent = yield* pluginAbsentByHost[config.host];
176 - if (!absent) return;
177 - yield* writeState(config.host, state);
178 - const label = HOST_LABELS[config.host];
111 + const host = config.host;
112 + if (
113 + host === undefined ||
114 + config.invocationOrigin === 'run' ||
115 + config.commandName === 'setup'
116 + ) {
117 + return;
118 + }
119 + if (!(yield* pluginAbsentByHost[host])) return;
120 + if (!(yield* claimHint(host))) return;
121 yield* terminal.error(
180 - `Tip: running under ${label} without the Composio plugin — 'composio setup' installs it.`
122 + `Tip: running under ${AGENT_HOST_LABELS[host]} without the Composio plugin — 'composio setup' installs it.`
123 );
124 }).pipe(Effect.ignore);
125 }
@@ -190,11 +132,9 @@ const DefaultConfigLayers = Layer.mergeAll(Path.layer, NodeOs.Default, BunFileSy
132 const readOptionalEnv = (name: string) =>
133 Effect.orDie(Config.option(Config.string(name)).pipe(Config.map(Option.getOrUndefined)));
134
193 -// Env reads bypass the CLI's runtime ConfigProvider (which prefixes every key
194 -// with COMPOSIO_) because these are host-owned variables under their raw names.
195 -const defaultConfig = Effect.gen(function* () {
196 - const path = yield* Path.Path;
197 - const os = yield* NodeOs;
135 +// Host-owned variables must bypass the CLI ConfigProvider, which prefixes
136 +// application keys with COMPOSIO_.
137 +const rawEnvironment = Effect.gen(function* () {
138 const claudeCode = yield* readOptionalEnv('CLAUDECODE');
139 const codexThreadId = yield* readOptionalEnv('CODEX_THREAD_ID');
140 const codexSandbox = yield* readOptionalEnv('CODEX_SANDBOX');
@@ -202,22 +142,40 @@ const defaultConfig = Effect.gen(function* () {
142 const claudeConfigDir = yield* readOptionalEnv('CLAUDE_CONFIG_DIR');
143 const codexHome = yield* readOptionalEnv('CODEX_HOME');
144 return {
205 - stateFile: path.join(os.homedir, '.composio', 'plugin-hint.json'),
206 - host: detectPluginHost({ claudeCode, codexThreadId, codexSandbox }),
145 + claudeCode,
146 + codexThreadId,
147 + codexSandbox,
148 invocationOrigin,
208 - claudeInstalledPluginsFile: path.join(
209 - claudeConfigDir ?? path.join(os.homedir, '.claude'),
210 - 'plugins',
211 - 'installed_plugins.json'
212 - ),
213 - codexConfigFile: path.join(codexHome ?? path.join(os.homedir, '.codex'), 'config.toml'),
214 - hintIntervalMs: HINT_INTERVAL_MS,
215 - } satisfies PluginHintConfig;
149 + claudeConfigDir,
150 + codexHome,
151 + };
152 }).pipe(Effect.withConfigProvider(ConfigProvider.fromEnv()));
153
154 +export const resolvePluginHintConfig = (argv: ReadonlyArray<string>) =>
155 + Effect.gen(function* () {
156 + const path = yield* Path.Path;
157 + const os = yield* NodeOs;
158 + const cacheDir = yield* setupCacheDir;
159 + const env = yield* rawEnvironment;
160 + return {
161 + stateDirectory: path.join(cacheDir, 'plugin-hints'),
162 + host: detectPluginHost(env),
163 + invocationOrigin: env.invocationOrigin,
164 + commandName: argv[2],
165 + claudeInstalledPluginsFile: path.join(
166 + env.claudeConfigDir ?? path.join(os.homedir, '.claude'),
167 + 'plugins',
168 + 'installed_plugins.json'
169 + ),
170 + codexConfigFile: path.join(env.codexHome ?? path.join(os.homedir, '.codex'), 'config.toml'),
171 + hintIntervalMs: HINT_INTERVAL_MS,
172 + } satisfies PluginHintConfig;
173 + });
174 +
175 /** Print the plugin acquisition hint when eligible. Never fails, never blocks on network. */
219 -export const showPluginAcquisitionHint = Effect.gen(function* () {
220 - const terminal = yield* TerminalUI;
221 - const config = yield* defaultConfig;
222 - yield* createPluginHint(config).showPluginHint(terminal);
223 -}).pipe(Effect.provide(DefaultConfigLayers));
176 +export const showPluginAcquisitionHint = (argv: ReadonlyArray<string>) =>
177 + Effect.gen(function* () {
178 + const terminal = yield* TerminalUI;
179 + const config = yield* resolvePluginHintConfig(argv);
180 + yield* createPluginHint(config).showPluginHint(terminal);
181 + }).pipe(Effect.provide(DefaultConfigLayers));
ts/packages/cli/src/services/setup.ts
+11 -5
@@ -7,23 +7,29 @@ import {
7 getPluginLifecycleSucceededEvent,
8 } from 'src/analytics/events';
9 import { APP_VERSION } from 'src/constants';
10 +import {
11 + AGENT_HOSTS,
12 + AGENT_HOST_LABELS,
13 + COMPOSIO_AGENT_PLUGIN_ID,
14 + type AgentHost,
15 +} from './agent-host';
16 import { CommandRunner, type CommandResult } from './command-runner';
17 import { SetupSkillInstaller } from './setup-skill-installer';
18
13 -export const SETUP_TARGETS = ['auto', 'claude', 'codex', 'all'] as const;
19 +export const SETUP_TARGETS = ['auto', ...AGENT_HOSTS, 'all'] as const;
20 export type SetupTarget = (typeof SETUP_TARGETS)[number];
15 -export type AgentHost = Exclude<SetupTarget, 'auto' | 'all'>;
21 +export type { AgentHost } from './agent-host';
22
23 const CLAUDE_PLUGIN_MARKETPLACE = {
24 name: 'composio',
25 source: 'https://github.com/ComposioHQ/composio-plugin-cc.git',
20 - plugin: 'composio@composio',
26 + plugin: COMPOSIO_AGENT_PLUGIN_ID,
27 } as const;
28
29 const CODEX_PLUGIN_MARKETPLACE = {
30 name: 'composio',
31 source: 'https://github.com/ComposioHQ/composio-plugin-openai.git',
26 - plugin: 'composio@composio',
32 + plugin: COMPOSIO_AGENT_PLUGIN_ID,
33 } as const;
34
35 export interface SetupTargetStatus {
@@ -297,7 +303,7 @@ const captureOptional = (adapter: SetupTargetAdapter, args: ReadonlyArray<string
303 )
304 );
305
300 -const targetLabel = (target: AgentHost): string => (target === 'claude' ? 'Claude Code' : 'Codex');
306 +const targetLabel = (target: AgentHost): string => AGENT_HOST_LABELS[target];
307
308 const hostUpdateCommand = (adapter: SetupTargetAdapter): string => `${adapter.executable} update`;
309
ts/packages/cli/test/src/services/plugin-hint.test.ts
+85 -146
@@ -1,19 +1,19 @@
1 -import { describe, it, expect, beforeEach, afterEach } from '@effect/vitest';
2 -import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
1 +import { afterEach, beforeEach, describe, expect, it, vi } from '@effect/vitest';
2 +import { BunFileSystem, BunPath } from '@effect/platform-bun';
3 +import { ConfigProvider, Effect, Layer } from 'effect';
4 +import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
5 import { tmpdir } from 'node:os';
6 import { dirname, join } from 'node:path';
7 import { Writable } from 'node:stream';
6 -import { BunFileSystem, BunPath } from '@effect/platform-bun';
7 -import { Effect, Layer } from 'effect';
8 -import { makeTerminalUI, type TerminalUI } from 'src/services/terminal-ui';
8 +import { extendConfigProvider } from 'src/services/config';
9 +import { defaultNodeOs, NodeOs } from 'src/services/node-os';
10 import {
11 createPluginHint,
12 detectPluginHost,
13 + resolvePluginHintConfig,
14 type PluginHintConfig,
13 - type PluginHintState,
15 } from 'src/services/plugin-hint';
15 -
16 -const PlatformLayers = Layer.mergeAll(BunFileSystem.layer, BunPath.layer);
16 +import { makeTerminalUI, type TerminalUI } from 'src/services/terminal-ui';
17
18 const DAY_MS = 24 * 60 * 60 * 1000;
19
@@ -22,14 +22,19 @@ beforeEach(() => {
22 tempDir = mkdtempSync(join(tmpdir(), 'plugin-hint-test-'));
23 });
24 afterEach(() => {
25 + vi.useRealTimers();
26 + vi.unstubAllEnvs();
27 rmSync(tempDir, { recursive: true, force: true });
28 });
29
30 +const PlatformLayers = Layer.mergeAll(BunFileSystem.layer, BunPath.layer);
31 +
32 function makeConfig(overrides?: Partial<PluginHintConfig>): PluginHintConfig {
33 return {
30 - stateFile: join(tempDir, '.composio', 'plugin-hint.json'),
34 + stateDirectory: join(tempDir, '.composio', 'plugin-hints'),
35 host: 'claude',
36 invocationOrigin: undefined,
37 + commandName: 'version',
38 claudeInstalledPluginsFile: join(tempDir, '.claude', 'plugins', 'installed_plugins.json'),
39 codexConfigFile: join(tempDir, '.codex', 'config.toml'),
40 hintIntervalMs: DAY_MS,
@@ -46,28 +51,18 @@ function writeFileAt(file: string, contents: string): void {
51 writeFileSync(file, contents);
52 }
53
49 -function writeHintState(config: PluginHintConfig, state: PluginHintState): void {
50 - writeFileAt(config.stateFile, JSON.stringify(state));
51 -}
52 -
54 function writeClaudePlugins(config: PluginHintConfig, plugins: Record<string, unknown[]>): void {
55 writeFileAt(config.claudeInstalledPluginsFile, JSON.stringify({ version: 2, plugins }));
56 }
57
58 describe('detectPluginHost', () => {
58 - it('detects Claude Code from CLAUDECODE', () => {
59 + it('detects supported hosts from non-empty markers', () => {
60 expect(
61 detectPluginHost({ claudeCode: '1', codexThreadId: undefined, codexSandbox: undefined })
62 ).toBe('claude');
62 - });
63 -
64 - it('detects Codex from CODEX_THREAD_ID', () => {
63 expect(
64 detectPluginHost({ claudeCode: undefined, codexThreadId: 'abc', codexSandbox: undefined })
65 ).toBe('codex');
68 - });
69 -
70 - it('detects Codex from CODEX_SANDBOX', () => {
66 expect(
67 detectPluginHost({
68 claudeCode: undefined,
@@ -77,19 +72,40 @@ describe('detectPluginHost', () => {
72 ).toBe('codex');
73 });
74
80 - it('prefers Claude Code when both markers are present', () => {
75 + it('prefers Claude Code when both hosts have non-empty markers', () => {
76 expect(
77 detectPluginHost({ claudeCode: '1', codexThreadId: 'abc', codexSandbox: undefined })
78 ).toBe('claude');
79 });
80
86 - it('detects no host without markers', () => {
81 + it('ignores empty and whitespace-only markers', () => {
82 expect(
88 - detectPluginHost({ claudeCode: undefined, codexThreadId: undefined, codexSandbox: undefined })
83 + detectPluginHost({ claudeCode: '', codexThreadId: ' ', codexSandbox: '\t' })
84 ).toBeUndefined();
85 });
86 });
87
88 +describe('resolvePluginHintConfig', () => {
89 + it.effect('stores throttle stamps under COMPOSIO_CACHE_DIR', () => {
90 + const cacheDir = join(tempDir, 'writable-cache');
91 + vi.stubEnv('COMPOSIO_CACHE_DIR', cacheDir);
92 + vi.stubEnv('CLAUDECODE', '1');
93 +
94 + return Effect.gen(function* () {
95 + const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
96 +
97 + expect(config.stateDirectory).toBe(join(cacheDir, 'plugin-hints'));
98 + expect(config.host).toBe('claude');
99 + expect(config.commandName).toBe('version');
100 + }).pipe(
101 + Effect.withConfigProvider(extendConfigProvider(ConfigProvider.fromEnv())),
102 + Effect.provide(
103 + Layer.merge(PlatformLayers, Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })))
104 + )
105 + );
106 + });
107 +});
108 +
109 describe('showPluginHint', () => {
110 let output: string[];
111
@@ -97,53 +113,38 @@ describe('showPluginHint', () => {
113 output = [];
114 });
115
100 - it.effect('shows the hint when the Claude plugin state file is missing', () =>
116 + it.effect('shows the hint when a host plugin is confidently absent', () =>
117 Effect.gen(function* () {
102 - const config = makeConfig();
118 + const claudeConfig = makeConfig();
119 + writeClaudePlugins(claudeConfig, { 'other@marketplace': [{ scope: 'user' }] });
120 + yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
121
104 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
122 + const codexConfig = makeConfig({ host: 'codex' });
123 + writeFileAt(codexConfig.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
124 + yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
125
106 - expect(output).toHaveLength(1);
126 + expect(output).toHaveLength(2);
127 expect(output[0]).toContain('Claude Code');
108 - expect(output[0]).toContain('composio setup');
109 - }).pipe(Effect.provide(PlatformLayers))
110 - );
111 -
112 - it.effect('shows the hint when the Claude plugin is not installed', () =>
113 - Effect.gen(function* () {
114 - const config = makeConfig();
115 - writeClaudePlugins(config, { 'other@marketplace': [{ scope: 'user' }] });
116 -
117 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
118 -
119 - expect(output).toHaveLength(1);
120 - }).pipe(Effect.provide(PlatformLayers))
121 - );
122 -
123 - it.effect('shows the hint when the Claude plugin entry has no installations', () =>
124 - Effect.gen(function* () {
125 - const config = makeConfig();
126 - writeClaudePlugins(config, { 'composio@composio': [] });
127 -
128 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
129 -
130 - expect(output).toHaveLength(1);
128 + expect(output[1]).toContain('Codex');
129 }).pipe(Effect.provide(PlatformLayers))
130 );
131
134 - it.effect('stays silent when the Claude plugin is installed', () =>
132 + it.effect('stays silent when the plugin is installed', () =>
133 Effect.gen(function* () {
136 - const config = makeConfig();
137 - writeClaudePlugins(config, { 'composio@composio': [{ scope: 'user' }] });
134 + const claudeConfig = makeConfig();
135 + writeClaudePlugins(claudeConfig, { 'composio@composio': [{ scope: 'user' }] });
136 + yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
137
139 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
138 + const codexConfig = makeConfig({ host: 'codex' });
139 + writeFileAt(codexConfig.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n');
140 + yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
141
142 expect(output).toEqual([]);
142 - expect(existsSync(config.stateFile)).toBe(false);
143 + expect(existsSync(claudeConfig.stateDirectory)).toBe(false);
144 }).pipe(Effect.provide(PlatformLayers))
145 );
146
146 - it.effect('stays silent when the Claude plugin state file is unreadable', () =>
147 + it.effect('stays silent when plugin state is unreadable', () =>
148 Effect.gen(function* () {
149 const config = makeConfig();
150 writeFileAt(config.claudeInstalledPluginsFile, 'not json{');
@@ -154,128 +155,66 @@ describe('showPluginHint', () => {
155 }).pipe(Effect.provide(PlatformLayers))
156 );
157
157 - it.effect('shows the hint when the Codex config has no plugin section', () =>
158 - Effect.gen(function* () {
159 - const config = makeConfig({ host: 'codex' });
160 - writeFileAt(config.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
161 -
162 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
163 -
164 - expect(output).toHaveLength(1);
165 - expect(output[0]).toContain('Codex');
166 - }).pipe(Effect.provide(PlatformLayers))
167 - );
168 -
169 - it.effect('shows the hint when the Codex config file is missing', () =>
170 - Effect.gen(function* () {
171 - const config = makeConfig({ host: 'codex' });
172 -
173 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
174 -
175 - expect(output).toHaveLength(1);
176 - }).pipe(Effect.provide(PlatformLayers))
177 - );
178 -
179 - it.effect('stays silent when the Codex config has the plugin section', () =>
180 - Effect.gen(function* () {
181 - const config = makeConfig({ host: 'codex' });
182 - writeFileAt(config.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n');
183 -
184 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
185 -
186 - expect(output).toEqual([]);
187 - }).pipe(Effect.provide(PlatformLayers))
188 - );
189 -
190 - it.effect('stays silent outside a plugin-capable host', () =>
158 + it.effect('stays silent outside a host, in run children, and for setup', () =>
159 Effect.gen(function* () {
192 - const config = makeConfig({ host: undefined });
160 + const configs = [
161 + makeConfig({ host: undefined }),
162 + makeConfig({ invocationOrigin: 'run' }),
163 + makeConfig({ commandName: 'setup' }),
164 + ];
165
194 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
195 -
196 - expect(output).toEqual([]);
197 - }).pipe(Effect.provide(PlatformLayers))
198 - );
199 -
200 - it.effect('stays silent when invoked from a composio run child', () =>
201 - Effect.gen(function* () {
202 - const config = makeConfig({ invocationOrigin: 'run' });
203 -
204 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
166 + yield* Effect.forEach(configs, config =>
167 + createPluginHint(config).showPluginHint(makeTerminal(output))
168 + );
169
170 expect(output).toEqual([]);
171 + expect(existsSync(configs[2]!.stateDirectory)).toBe(false);
172 }).pipe(Effect.provide(PlatformLayers))
173 );
174
210 - it.effect('stays silent when the hint was shown within the interval', () =>
175 + it.effect('allows only one concurrent process to claim a host hint', () =>
176 Effect.gen(function* () {
177 const config = makeConfig();
213 - writeHintState(config, { lastHintShown: { claude: new Date().toISOString() } });
214 -
215 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
178
217 - expect(output).toEqual([]);
218 - }).pipe(Effect.provide(PlatformLayers))
219 - );
220 -
221 - it.effect('shows the hint again after the interval elapses', () =>
222 - Effect.gen(function* () {
223 - const config = makeConfig();
224 - writeHintState(config, { lastHintShown: { claude: '2000-01-01T00:00:00.000Z' } });
225 -
226 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
179 + yield* Effect.all(
180 + Array.from({ length: 20 }, () =>
181 + createPluginHint(config).showPluginHint(makeTerminal(output))
182 + ),
183 + { concurrency: 'unbounded' }
184 + );
185
186 expect(output).toHaveLength(1);
187 + expect(existsSync(join(config.stateDirectory, 'claude.stamp'))).toBe(true);
188 }).pipe(Effect.provide(PlatformLayers))
189 );
190
232 - it.effect('throttles Claude and Codex independently', () =>
191 + it.effect('throttles each host independently', () =>
192 Effect.gen(function* () {
193 const claudeConfig = makeConfig({ host: 'claude' });
194 const codexConfig = makeConfig({ host: 'codex' });
195
196 + yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
197 + yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
198 yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
199 yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
200
201 expect(output).toHaveLength(2);
241 - expect(output[0]).toContain('Claude Code');
242 - expect(output[1]).toContain('Codex');
243 - }).pipe(Effect.provide(PlatformLayers))
244 - );
245 -
246 - it.effect('honors the legacy global timestamp during state migration', () =>
247 - Effect.gen(function* () {
248 - const config = makeConfig({ host: 'codex' });
249 - writeFileAt(config.stateFile, JSON.stringify({ lastHintShown: new Date().toISOString() }));
250 -
251 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
252 -
253 - expect(output).toEqual([]);
254 - }).pipe(Effect.provide(PlatformLayers))
255 - );
256 -
257 - it.effect('shows the hint when the throttle state file is unreadable', () =>
258 - Effect.gen(function* () {
259 - const config = makeConfig();
260 - writeFileAt(config.stateFile, 'not json{');
261 -
262 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
263 -
264 - expect(output).toHaveLength(1);
202 }).pipe(Effect.provide(PlatformLayers))
203 );
204
268 - it.effect('stamps the throttle state when the hint is shown', () =>
205 + it.effect('retires a stale stamp and shows the hint again', () =>
206 Effect.gen(function* () {
207 + vi.useFakeTimers();
208 + vi.setSystemTime(new Date('2026-07-29T00:00:00.000Z'));
209 const config = makeConfig();
210 + const stamp = join(config.stateDirectory, 'claude.stamp');
211 + writeFileAt(stamp, '');
212 + const stale = new Date('2026-07-27T00:00:00.000Z');
213 + utimesSync(stamp, stale, stale);
214
215 yield* createPluginHint(config).showPluginHint(makeTerminal(output));
216
217 expect(output).toHaveLength(1);
275 - expect(existsSync(config.stateFile)).toBe(true);
276 - output = [];
277 - yield* createPluginHint(config).showPluginHint(makeTerminal(output));
278 - expect(output).toEqual([]);
218 }).pipe(Effect.provide(PlatformLayers))
219 );
220