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