Skip to content

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 Jhunjhunwalaaf772565f7fc
diff --git a/mise.lock b/mise.lock
index 56dd092f1..4666d7776 100644
--- a/mise.lock
+++ b/mise.lock
@@ -89,23 +89,23 @@ version = "3.12.13"
backend = "core:python"
[tools.python."platforms.linux-arm64"]
-checksum = "sha256:e125d3e75034fe75d49ae8577b53758b0bb7d7817fadde2c020ad2cf7afe64c4"
-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"
+checksum = "sha256:f226576b91491ffa5739aa85726521e9031f4d87f80627d64ed348ac77cb31e9"
+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"
provenance = "github-attestations"
[tools.python."platforms.linux-x64"]
-checksum = "sha256:7ceaf4360f4b4ab44f31d8217cfdc70df8e12b61d9561b4900ee7af87176e50d"
-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"
+checksum = "sha256:5854aa6ec71cad00334d5065633c210b2e7feb40956767a59a91791cadcf0b79"
+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"
provenance = "github-attestations"
[tools.python."platforms.macos-arm64"]
-checksum = "sha256:2f18cdef4125ca1440dd1ba00ebcb267526efb532138c0860438f755ea4eebac"
-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"
+checksum = "sha256:9a1e9e06175c10efd8378b904b07fa21bd791ab3345d7cdffeb4a76c9ff55903"
+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"
provenance = "github-attestations"
[tools.python."platforms.macos-x64"]
-checksum = "sha256:e654c21d0ba53e2c671868d4112fac5874deca4c35226d36c5cfe53bc5c9cd71"
-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"
+checksum = "sha256:8e6b7e6533bdf746287008edf91102e7bee0a6ca1d24f16c4514237cafd706c5"
+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"
provenance = "github-attestations"
[[tools.uv]]
@@ -115,19 +115,15 @@ backend = "aqua:astral-sh/uv"
[tools.uv."platforms.linux-arm64"]
checksum = "sha256:87925376fa1e59de23582e1cbd81d6aabd16611e871ad085e09be2c2fa12689d"
url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-aarch64-unknown-linux-musl.tar.gz"
-url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160192"
[tools.uv."platforms.linux-x64"]
checksum = "sha256:6a37f712ae90c7b8cf364fe751144d7acc2479d6b336378111e74cc7fb14fa7b"
url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-x86_64-unknown-linux-musl.tar.gz"
-url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160235"
[tools.uv."platforms.macos-arm64"]
checksum = "sha256:bb63d43c40a301d889a985223ee8ce540be199e98b3f27ed8477823869a0a605"
url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-aarch64-apple-darwin.tar.gz"
-url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160180"
[tools.uv."platforms.macos-x64"]
checksum = "sha256:b5f91770e55761b32c9618757ef23ded6671bb9ca0ddf5737eea60dddd493fe9"
url = "https://github.com/astral-sh/uv/releases/download/0.8.19/uv-x86_64-apple-darwin.tar.gz"
-url_api = "https://api.github.com/repos/astral-sh/uv/releases/assets/295160227"
diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.ts
index 1bd142fe9..051a361a6 100644
--- a/ts/packages/cli/src/cli-main.ts
+++ b/ts/packages/cli/src/cli-main.ts
@@ -175,7 +175,7 @@ const runWithTelemetry = Effect.gen(function* () {
});
showUpdateNotice.pipe(
- Effect.andThen(showPluginAcquisitionHint),
+ Effect.andThen(showPluginAcquisitionHint(process.argv)),
Effect.andThen(runWithTelemetry),
Effect.catchIf(ValidationError.isValidationError, error => {
return Effect.gen(function* () {
diff --git a/ts/packages/cli/src/commands/setup.cmd.ts b/ts/packages/cli/src/commands/setup.cmd.ts
index b5458731a..e0ebae285 100644
--- a/ts/packages/cli/src/commands/setup.cmd.ts
+++ b/ts/packages/cli/src/commands/setup.cmd.ts
@@ -7,6 +7,7 @@ import {
getSetupSkippedEvent,
} from 'src/analytics/events';
import { APP_VERSION } from 'src/constants';
+import { AGENT_HOST_LABELS } from 'src/services/agent-host';
import {
detectSetupTargets,
inspectSetupTargets,
@@ -42,13 +43,8 @@ const uninstall = Options.boolean('uninstall').pipe(
Options.withDescription('Uninstall Composio plugins instead of installing them')
);
-const TARGET_LABELS: Readonly<Record<AgentHost, string>> = {
- claude: 'Claude Code',
- codex: 'Codex',
-};
-
const formatTargets = (targets: ReadonlyArray<AgentHost>): string =>
- targets.map(target => TARGET_LABELS[target]).join(' and ');
+ targets.map(target => AGENT_HOST_LABELS[target]).join(' and ');
const errorMessage = (error: unknown): string =>
Predicate.isError(error) ? error.message : String(error);
@@ -170,12 +166,12 @@ const setupBaseCmd = Command.make(
for (const status of installed) {
yield* ui.log.success(
- `The Composio plugin for ${TARGET_LABELS[status.target]} is installed.`
+ `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is installed.`
);
}
for (const status of notInstalled) {
yield* ui.log.info(
- `The Composio plugin for ${TARGET_LABELS[status.target]} is not installed.`
+ `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is not installed.`
);
}
@@ -207,7 +203,7 @@ const setupBaseCmd = Command.make(
for (const result of results) {
if (!result.plugin_changed) continue;
yield* ui.log.success(
- `Successfully uninstalled the Composio plugin for ${TARGET_LABELS[result.target]}.`
+ `Successfully uninstalled the Composio plugin for ${AGENT_HOST_LABELS[result.target]}.`
);
}
yield* ui.outro('Composio plugin uninstall complete.');
@@ -216,7 +212,7 @@ const setupBaseCmd = Command.make(
for (const status of inspected.filter(isSetupPluginReady)) {
yield* ui.log.success(
- `The Composio plugin for ${TARGET_LABELS[status.target]} is already installed and enabled.`
+ `The Composio plugin for ${AGENT_HOST_LABELS[status.target]} is already installed and enabled.`
);
}
@@ -267,7 +263,7 @@ const setupBaseCmd = Command.make(
if (!initial.plugin_installed) action = 'installed and enabled';
else if (!initial.plugin_enabled) action = 'enabled';
yield* ui.log.success(
- `Successfully ${action} the Composio plugin for ${TARGET_LABELS[result.target]}.`
+ `Successfully ${action} the Composio plugin for ${AGENT_HOST_LABELS[result.target]}.`
);
}
diff --git a/ts/packages/cli/src/services/agent-host.ts b/ts/packages/cli/src/services/agent-host.ts
new file mode 100644
index 000000000..a1bc674ca
--- /dev/null
+++ b/ts/packages/cli/src/services/agent-host.ts
@@ -0,0 +1,10 @@
+export const AGENT_HOSTS = ['claude', 'codex'] as const;
+
+export type AgentHost = (typeof AGENT_HOSTS)[number];
+
+export const AGENT_HOST_LABELS: Readonly<Record<AgentHost, string>> = {
+ claude: 'Claude Code',
+ codex: 'Codex',
+};
+
+export const COMPOSIO_AGENT_PLUGIN_ID = 'composio@composio';
diff --git a/ts/packages/cli/src/services/plugin-hint.ts b/ts/packages/cli/src/services/plugin-hint.ts
index 99ab8a6f2..378da0b08 100644
--- a/ts/packages/cli/src/services/plugin-hint.ts
+++ b/ts/packages/cli/src/services/plugin-hint.ts
@@ -1,28 +1,19 @@
import { FileSystem, Path } from '@effect/platform';
import { BunFileSystem } from '@effect/platform-bun';
import { Config, ConfigProvider, Effect, Layer, Option, Schema } from 'effect';
+import { setupCacheDir } from 'src/effects/setup-cache-dir';
+import { AGENT_HOST_LABELS, COMPOSIO_AGENT_PLUGIN_ID, type AgentHost } from './agent-host';
import { NodeOs } from './node-os';
import { TerminalUI } from './terminal-ui';
/**
* One-line acquisition hint for the Composio agent plugin.
*
- * When the bare CLI runs inside a plugin-capable agent host (Claude Code,
- * Codex) and the Composio plugin is not installed there, print one throttled
- * tip to stderr. The primary audience is the agent driving the CLI through a
- * non-TTY shell, so unlike the rest of the CLI's decoration this line is NOT
- * gated on stderr being a TTY.
+ * The primary audience is the agent driving the CLI through a non-TTY shell,
+ * so this line is intentionally not gated on stderr being a TTY.
*/
const HINT_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const PLUGIN_ID = 'composio@composio';
-
-export type PluginHost = 'claude' | 'codex';
-
-const HOST_LABELS: Record<PluginHost, string> = {
- claude: 'Claude Code',
- codex: 'Codex',
-};
export interface HostEnvMarkers {
readonly claudeCode: string | undefined;
@@ -30,63 +21,15 @@ export interface HostEnvMarkers {
readonly codexSandbox: string | undefined;
}
-export function detectPluginHost(markers: HostEnvMarkers): PluginHost | undefined {
- if (markers.claudeCode !== undefined) return 'claude';
- if (markers.codexThreadId !== undefined || markers.codexSandbox !== undefined) return 'codex';
- return undefined;
-}
+const isPresent = (value: string | undefined): boolean =>
+ value !== undefined && value.trim().length > 0;
-export interface PluginHintState {
- readonly lastHintShown: {
- readonly claude?: string; // ISO-8601
- readonly codex?: string; // ISO-8601
- };
+export function detectPluginHost(markers: HostEnvMarkers): AgentHost | undefined {
+ if (isPresent(markers.claudeCode)) return 'claude';
+ if (isPresent(markers.codexThreadId) || isPresent(markers.codexSandbox)) return 'codex';
+ return undefined;
}
-const CurrentPluginHintStateSchema = Schema.Struct({
- lastHintShown: Schema.Struct({
- claude: Schema.optional(Schema.String),
- codex: Schema.optional(Schema.String),
- }),
-});
-
-const LegacyPluginHintStateSchema = Schema.Struct({
- lastHintShown: Schema.String,
-});
-
-const PluginHintStateSchema = Schema.parseJson(
- Schema.Union(CurrentPluginHintStateSchema, LegacyPluginHintStateSchema)
-);
-
-const normalizePluginHintState = (
- state:
- | Schema.Schema.Type<typeof CurrentPluginHintStateSchema>
- | {
- readonly lastHintShown: string;
- }
-): PluginHintState => {
- const lastHintShown = state.lastHintShown;
- if (typeof lastHintShown === 'string') {
- return {
- // Preserve the legacy global throttle during migration.
- lastHintShown: {
- claude: lastHintShown,
- codex: lastHintShown,
- },
- };
- }
- return { lastHintShown };
-};
-
-const PluginHintStateOutputSchema = Schema.parseJson(
- Schema.Struct({
- lastHintShown: Schema.Struct({
- claude: Schema.optional(Schema.String),
- codex: Schema.optional(Schema.String),
- }),
- })
-);
-
const InstalledPluginsSchema = Schema.parseJson(
Schema.Struct({
plugins: Schema.Record({ key: Schema.String, value: Schema.Array(Schema.Unknown) }),
@@ -94,73 +37,70 @@ const InstalledPluginsSchema = Schema.parseJson(
);
export interface PluginHintConfig {
- readonly stateFile: string;
- readonly host: PluginHost | undefined;
+ readonly stateDirectory: string;
+ readonly host: AgentHost | undefined;
readonly invocationOrigin: string | undefined;
+ readonly commandName: string | undefined;
readonly claudeInstalledPluginsFile: string;
readonly codexConfigFile: string;
readonly hintIntervalMs: number;
}
export function createPluginHint(config: PluginHintConfig) {
- const readState = Effect.gen(function* () {
- const fs = yield* FileSystem.FileSystem;
- const rawState = yield* fs.readFileString(config.stateFile);
- return normalizePluginHintState(yield* Schema.decodeUnknown(PluginHintStateSchema)(rawState));
- });
-
- const writeState = (host: PluginHost, previous: Option.Option<PluginHintState>) =>
+ const claimHint = (host: AgentHost) =>
Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
const path = yield* Path.Path;
- const state: PluginHintState = {
- lastHintShown: {
- ...(Option.isSome(previous) ? previous.value.lastHintShown : {}),
- [host]: new Date().toISOString(),
- },
- };
- const encoded = yield* Schema.encode(PluginHintStateOutputSchema)(state);
- yield* fs.makeDirectory(path.dirname(config.stateFile), { recursive: true });
- yield* fs.writeFileString(config.stateFile, encoded);
- });
-
- const shownWithinInterval = (
- state: Option.Option<PluginHintState>,
- host: PluginHost
- ): boolean => {
- if (Option.isNone(state)) return false;
- const lastHintShown = state.value.lastHintShown[host];
- if (lastHintShown === undefined) return false;
- const shownAt = new Date(lastHintShown).getTime();
- if (!Number.isFinite(shownAt)) return false;
- return Date.now() - shownAt < config.hintIntervalMs;
- };
+ const stampPath = path.join(config.stateDirectory, `${host}.stamp`);
+ yield* fs.makeDirectory(config.stateDirectory, { recursive: true });
+
+ const stampInfo = yield* Effect.option(fs.stat(stampPath));
+ if (Option.isSome(stampInfo)) {
+ const shownAt = Option.getOrUndefined(stampInfo.value.mtime)?.getTime();
+ if (
+ shownAt !== undefined &&
+ Number.isFinite(shownAt) &&
+ Date.now() - shownAt < config.hintIntervalMs
+ ) {
+ return false;
+ }
+
+ // Retiring via rename means only one concurrent process can replace a
+ // stale stamp. Everyone else either sees the new stamp or loses the
+ // exclusive create below.
+ const retiredPath = `${stampPath}.${crypto.randomUUID()}`;
+ const retired = yield* Effect.option(fs.rename(stampPath, retiredPath));
+ yield* fs.remove(retiredPath, { force: true }).pipe(Effect.ignore);
+ if (Option.isNone(retired)) return false;
+ }
+
+ return yield* Effect.scoped(fs.open(stampPath, { flag: 'wx' })).pipe(
+ Effect.as(true),
+ Effect.orElseSucceed(() => false)
+ );
+ }).pipe(Effect.orElseSucceed(() => false));
// "Confidently absent" only: a missing state file means the plugin was never
// installed, while an unreadable or unrecognized one suppresses the hint.
const claudePluginAbsent = Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
- const fileExists = yield* fs.exists(config.claudeInstalledPluginsFile);
- if (!fileExists) return true;
+ if (!(yield* fs.exists(config.claudeInstalledPluginsFile))) return true;
const raw = yield* fs.readFileString(config.claudeInstalledPluginsFile);
const decoded = yield* Effect.option(Schema.decodeUnknown(InstalledPluginsSchema)(raw));
if (Option.isNone(decoded)) return false;
- const installs = decoded.value.plugins[PLUGIN_ID];
- if (installs === undefined) return true;
- return installs.length === 0;
+ const installs = decoded.value.plugins[COMPOSIO_AGENT_PLUGIN_ID];
+ return installs === undefined || installs.length === 0;
});
const codexPluginAbsent = Effect.gen(function* () {
const fs = yield* FileSystem.FileSystem;
- const fileExists = yield* fs.exists(config.codexConfigFile);
- if (!fileExists) return true;
+ if (!(yield* fs.exists(config.codexConfigFile))) return true;
const raw = yield* fs.readFileString(config.codexConfigFile);
- return !raw.includes(`[plugins."${PLUGIN_ID}"]`);
+ return !raw.includes(`[plugins."${COMPOSIO_AGENT_PLUGIN_ID}"]`);
});
- const pluginAbsentByHost: Record<
- PluginHost,
- Effect.Effect<boolean, unknown, FileSystem.FileSystem>
+ const pluginAbsentByHost: Readonly<
+ Record<AgentHost, Effect.Effect<boolean, unknown, FileSystem.FileSystem>>
> = {
claude: claudePluginAbsent,
codex: codexPluginAbsent,
@@ -168,16 +108,18 @@ export function createPluginHint(config: PluginHintConfig) {
function showPluginHint(terminal: Pick<TerminalUI, 'error'>) {
return Effect.gen(function* () {
- if (config.host === undefined) return;
- if (config.invocationOrigin === 'run') return;
- const state = yield* Effect.option(readState);
- if (shownWithinInterval(state, config.host)) return;
- const absent = yield* pluginAbsentByHost[config.host];
- if (!absent) return;
- yield* writeState(config.host, state);
- const label = HOST_LABELS[config.host];
+ const host = config.host;
+ if (
+ host === undefined ||
+ config.invocationOrigin === 'run' ||
+ config.commandName === 'setup'
+ ) {
+ return;
+ }
+ if (!(yield* pluginAbsentByHost[host])) return;
+ if (!(yield* claimHint(host))) return;
yield* terminal.error(
- `Tip: running under ${label} without the Composio plugin — 'composio setup' installs it.`
+ `Tip: running under ${AGENT_HOST_LABELS[host]} without the Composio plugin — 'composio setup' installs it.`
);
}).pipe(Effect.ignore);
}
@@ -190,11 +132,9 @@ const DefaultConfigLayers = Layer.mergeAll(Path.layer, NodeOs.Default, BunFileSy
const readOptionalEnv = (name: string) =>
Effect.orDie(Config.option(Config.string(name)).pipe(Config.map(Option.getOrUndefined)));
-// Env reads bypass the CLI's runtime ConfigProvider (which prefixes every key
-// with COMPOSIO_) because these are host-owned variables under their raw names.
-const defaultConfig = Effect.gen(function* () {
- const path = yield* Path.Path;
- const os = yield* NodeOs;
+// Host-owned variables must bypass the CLI ConfigProvider, which prefixes
+// application keys with COMPOSIO_.
+const rawEnvironment = Effect.gen(function* () {
const claudeCode = yield* readOptionalEnv('CLAUDECODE');
const codexThreadId = yield* readOptionalEnv('CODEX_THREAD_ID');
const codexSandbox = yield* readOptionalEnv('CODEX_SANDBOX');
@@ -202,22 +142,40 @@ const defaultConfig = Effect.gen(function* () {
const claudeConfigDir = yield* readOptionalEnv('CLAUDE_CONFIG_DIR');
const codexHome = yield* readOptionalEnv('CODEX_HOME');
return {
- stateFile: path.join(os.homedir, '.composio', 'plugin-hint.json'),
- host: detectPluginHost({ claudeCode, codexThreadId, codexSandbox }),
+ claudeCode,
+ codexThreadId,
+ codexSandbox,
invocationOrigin,
- claudeInstalledPluginsFile: path.join(
- claudeConfigDir ?? path.join(os.homedir, '.claude'),
- 'plugins',
- 'installed_plugins.json'
- ),
- codexConfigFile: path.join(codexHome ?? path.join(os.homedir, '.codex'), 'config.toml'),
- hintIntervalMs: HINT_INTERVAL_MS,
- } satisfies PluginHintConfig;
+ claudeConfigDir,
+ codexHome,
+ };
}).pipe(Effect.withConfigProvider(ConfigProvider.fromEnv()));
+export const resolvePluginHintConfig = (argv: ReadonlyArray<string>) =>
+ Effect.gen(function* () {
+ const path = yield* Path.Path;
+ const os = yield* NodeOs;
+ const cacheDir = yield* setupCacheDir;
+ const env = yield* rawEnvironment;
+ return {
+ stateDirectory: path.join(cacheDir, 'plugin-hints'),
+ host: detectPluginHost(env),
+ invocationOrigin: env.invocationOrigin,
+ commandName: argv[2],
+ claudeInstalledPluginsFile: path.join(
+ env.claudeConfigDir ?? path.join(os.homedir, '.claude'),
+ 'plugins',
+ 'installed_plugins.json'
+ ),
+ codexConfigFile: path.join(env.codexHome ?? path.join(os.homedir, '.codex'), 'config.toml'),
+ hintIntervalMs: HINT_INTERVAL_MS,
+ } satisfies PluginHintConfig;
+ });
+
/** Print the plugin acquisition hint when eligible. Never fails, never blocks on network. */
-export const showPluginAcquisitionHint = Effect.gen(function* () {
- const terminal = yield* TerminalUI;
- const config = yield* defaultConfig;
- yield* createPluginHint(config).showPluginHint(terminal);
-}).pipe(Effect.provide(DefaultConfigLayers));
+export const showPluginAcquisitionHint = (argv: ReadonlyArray<string>) =>
+ Effect.gen(function* () {
+ const terminal = yield* TerminalUI;
+ const config = yield* resolvePluginHintConfig(argv);
+ yield* createPluginHint(config).showPluginHint(terminal);
+ }).pipe(Effect.provide(DefaultConfigLayers));
diff --git a/ts/packages/cli/src/services/setup.ts b/ts/packages/cli/src/services/setup.ts
index 73523433e..6a76567c7 100644
--- a/ts/packages/cli/src/services/setup.ts
+++ b/ts/packages/cli/src/services/setup.ts
@@ -7,23 +7,29 @@ import {
getPluginLifecycleSucceededEvent,
} from 'src/analytics/events';
import { APP_VERSION } from 'src/constants';
+import {
+ AGENT_HOSTS,
+ AGENT_HOST_LABELS,
+ COMPOSIO_AGENT_PLUGIN_ID,
+ type AgentHost,
+} from './agent-host';
import { CommandRunner, type CommandResult } from './command-runner';
import { SetupSkillInstaller } from './setup-skill-installer';
-export const SETUP_TARGETS = ['auto', 'claude', 'codex', 'all'] as const;
+export const SETUP_TARGETS = ['auto', ...AGENT_HOSTS, 'all'] as const;
export type SetupTarget = (typeof SETUP_TARGETS)[number];
-export type AgentHost = Exclude<SetupTarget, 'auto' | 'all'>;
+export type { AgentHost } from './agent-host';
const CLAUDE_PLUGIN_MARKETPLACE = {
name: 'composio',
source: 'https://github.com/ComposioHQ/composio-plugin-cc.git',
- plugin: 'composio@composio',
+ plugin: COMPOSIO_AGENT_PLUGIN_ID,
} as const;
const CODEX_PLUGIN_MARKETPLACE = {
name: 'composio',
source: 'https://github.com/ComposioHQ/composio-plugin-openai.git',
- plugin: 'composio@composio',
+ plugin: COMPOSIO_AGENT_PLUGIN_ID,
} as const;
export interface SetupTargetStatus {
@@ -297,7 +303,7 @@ const captureOptional = (adapter: SetupTargetAdapter, args: ReadonlyArray<string
)
);
-const targetLabel = (target: AgentHost): string => (target === 'claude' ? 'Claude Code' : 'Codex');
+const targetLabel = (target: AgentHost): string => AGENT_HOST_LABELS[target];
const hostUpdateCommand = (adapter: SetupTargetAdapter): string => `${adapter.executable} update`;
diff --git a/ts/packages/cli/test/src/services/plugin-hint.test.ts b/ts/packages/cli/test/src/services/plugin-hint.test.ts
index 613e6cc37..4f03ff9f0 100644
--- a/ts/packages/cli/test/src/services/plugin-hint.test.ts
+++ b/ts/packages/cli/test/src/services/plugin-hint.test.ts
@@ -1,19 +1,19 @@
-import { describe, it, expect, beforeEach, afterEach } from '@effect/vitest';
-import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { afterEach, beforeEach, describe, expect, it, vi } from '@effect/vitest';
+import { BunFileSystem, BunPath } from '@effect/platform-bun';
+import { ConfigProvider, Effect, Layer } from 'effect';
+import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { Writable } from 'node:stream';
-import { BunFileSystem, BunPath } from '@effect/platform-bun';
-import { Effect, Layer } from 'effect';
-import { makeTerminalUI, type TerminalUI } from 'src/services/terminal-ui';
+import { extendConfigProvider } from 'src/services/config';
+import { defaultNodeOs, NodeOs } from 'src/services/node-os';
import {
createPluginHint,
detectPluginHost,
+ resolvePluginHintConfig,
type PluginHintConfig,
- type PluginHintState,
} from 'src/services/plugin-hint';
-
-const PlatformLayers = Layer.mergeAll(BunFileSystem.layer, BunPath.layer);
+import { makeTerminalUI, type TerminalUI } from 'src/services/terminal-ui';
const DAY_MS = 24 * 60 * 60 * 1000;
@@ -22,14 +22,19 @@ beforeEach(() => {
tempDir = mkdtempSync(join(tmpdir(), 'plugin-hint-test-'));
});
afterEach(() => {
+ vi.useRealTimers();
+ vi.unstubAllEnvs();
rmSync(tempDir, { recursive: true, force: true });
});
+const PlatformLayers = Layer.mergeAll(BunFileSystem.layer, BunPath.layer);
+
function makeConfig(overrides?: Partial<PluginHintConfig>): PluginHintConfig {
return {
- stateFile: join(tempDir, '.composio', 'plugin-hint.json'),
+ stateDirectory: join(tempDir, '.composio', 'plugin-hints'),
host: 'claude',
invocationOrigin: undefined,
+ commandName: 'version',
claudeInstalledPluginsFile: join(tempDir, '.claude', 'plugins', 'installed_plugins.json'),
codexConfigFile: join(tempDir, '.codex', 'config.toml'),
hintIntervalMs: DAY_MS,
@@ -46,28 +51,18 @@ function writeFileAt(file: string, contents: string): void {
writeFileSync(file, contents);
}
-function writeHintState(config: PluginHintConfig, state: PluginHintState): void {
- writeFileAt(config.stateFile, JSON.stringify(state));
-}
-
function writeClaudePlugins(config: PluginHintConfig, plugins: Record<string, unknown[]>): void {
writeFileAt(config.claudeInstalledPluginsFile, JSON.stringify({ version: 2, plugins }));
}
describe('detectPluginHost', () => {
- it('detects Claude Code from CLAUDECODE', () => {
+ it('detects supported hosts from non-empty markers', () => {
expect(
detectPluginHost({ claudeCode: '1', codexThreadId: undefined, codexSandbox: undefined })
).toBe('claude');
- });
-
- it('detects Codex from CODEX_THREAD_ID', () => {
expect(
detectPluginHost({ claudeCode: undefined, codexThreadId: 'abc', codexSandbox: undefined })
).toBe('codex');
- });
-
- it('detects Codex from CODEX_SANDBOX', () => {
expect(
detectPluginHost({
claudeCode: undefined,
@@ -77,19 +72,40 @@ describe('detectPluginHost', () => {
).toBe('codex');
});
- it('prefers Claude Code when both markers are present', () => {
+ it('prefers Claude Code when both hosts have non-empty markers', () => {
expect(
detectPluginHost({ claudeCode: '1', codexThreadId: 'abc', codexSandbox: undefined })
).toBe('claude');
});
- it('detects no host without markers', () => {
+ it('ignores empty and whitespace-only markers', () => {
expect(
- detectPluginHost({ claudeCode: undefined, codexThreadId: undefined, codexSandbox: undefined })
+ detectPluginHost({ claudeCode: '', codexThreadId: ' ', codexSandbox: '\t' })
).toBeUndefined();
});
});
+describe('resolvePluginHintConfig', () => {
+ it.effect('stores throttle stamps under COMPOSIO_CACHE_DIR', () => {
+ const cacheDir = join(tempDir, 'writable-cache');
+ vi.stubEnv('COMPOSIO_CACHE_DIR', cacheDir);
+ vi.stubEnv('CLAUDECODE', '1');
+
+ return Effect.gen(function* () {
+ const config = yield* resolvePluginHintConfig(['/bin/bun', '/cli/bin.ts', 'version']);
+
+ expect(config.stateDirectory).toBe(join(cacheDir, 'plugin-hints'));
+ expect(config.host).toBe('claude');
+ expect(config.commandName).toBe('version');
+ }).pipe(
+ Effect.withConfigProvider(extendConfigProvider(ConfigProvider.fromEnv())),
+ Effect.provide(
+ Layer.merge(PlatformLayers, Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })))
+ )
+ );
+ });
+});
+
describe('showPluginHint', () => {
let output: string[];
@@ -97,53 +113,38 @@ describe('showPluginHint', () => {
output = [];
});
- it.effect('shows the hint when the Claude plugin state file is missing', () =>
+ it.effect('shows the hint when a host plugin is confidently absent', () =>
Effect.gen(function* () {
- const config = makeConfig();
+ const claudeConfig = makeConfig();
+ writeClaudePlugins(claudeConfig, { 'other@marketplace': [{ scope: 'user' }] });
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
+ const codexConfig = makeConfig({ host: 'codex' });
+ writeFileAt(codexConfig.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
- expect(output).toHaveLength(1);
+ expect(output).toHaveLength(2);
expect(output[0]).toContain('Claude Code');
- expect(output[0]).toContain('composio setup');
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('shows the hint when the Claude plugin is not installed', () =>
- Effect.gen(function* () {
- const config = makeConfig();
- writeClaudePlugins(config, { 'other@marketplace': [{ scope: 'user' }] });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toHaveLength(1);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('shows the hint when the Claude plugin entry has no installations', () =>
- Effect.gen(function* () {
- const config = makeConfig();
- writeClaudePlugins(config, { 'composio@composio': [] });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toHaveLength(1);
+ expect(output[1]).toContain('Codex');
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('stays silent when the Claude plugin is installed', () =>
+ it.effect('stays silent when the plugin is installed', () =>
Effect.gen(function* () {
- const config = makeConfig();
- writeClaudePlugins(config, { 'composio@composio': [{ scope: 'user' }] });
+ const claudeConfig = makeConfig();
+ writeClaudePlugins(claudeConfig, { 'composio@composio': [{ scope: 'user' }] });
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
+ const codexConfig = makeConfig({ host: 'codex' });
+ writeFileAt(codexConfig.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n');
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
expect(output).toEqual([]);
- expect(existsSync(config.stateFile)).toBe(false);
+ expect(existsSync(claudeConfig.stateDirectory)).toBe(false);
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('stays silent when the Claude plugin state file is unreadable', () =>
+ it.effect('stays silent when plugin state is unreadable', () =>
Effect.gen(function* () {
const config = makeConfig();
writeFileAt(config.claudeInstalledPluginsFile, 'not json{');
@@ -154,128 +155,66 @@ describe('showPluginHint', () => {
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('shows the hint when the Codex config has no plugin section', () =>
- Effect.gen(function* () {
- const config = makeConfig({ host: 'codex' });
- writeFileAt(config.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n');
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toHaveLength(1);
- expect(output[0]).toContain('Codex');
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('shows the hint when the Codex config file is missing', () =>
- Effect.gen(function* () {
- const config = makeConfig({ host: 'codex' });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toHaveLength(1);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('stays silent when the Codex config has the plugin section', () =>
- Effect.gen(function* () {
- const config = makeConfig({ host: 'codex' });
- writeFileAt(config.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n');
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toEqual([]);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('stays silent outside a plugin-capable host', () =>
+ it.effect('stays silent outside a host, in run children, and for setup', () =>
Effect.gen(function* () {
- const config = makeConfig({ host: undefined });
+ const configs = [
+ makeConfig({ host: undefined }),
+ makeConfig({ invocationOrigin: 'run' }),
+ makeConfig({ commandName: 'setup' }),
+ ];
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toEqual([]);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('stays silent when invoked from a composio run child', () =>
- Effect.gen(function* () {
- const config = makeConfig({ invocationOrigin: 'run' });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
+ yield* Effect.forEach(configs, config =>
+ createPluginHint(config).showPluginHint(makeTerminal(output))
+ );
expect(output).toEqual([]);
+ expect(existsSync(configs[2]!.stateDirectory)).toBe(false);
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('stays silent when the hint was shown within the interval', () =>
+ it.effect('allows only one concurrent process to claim a host hint', () =>
Effect.gen(function* () {
const config = makeConfig();
- writeHintState(config, { lastHintShown: { claude: new Date().toISOString() } });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
- expect(output).toEqual([]);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('shows the hint again after the interval elapses', () =>
- Effect.gen(function* () {
- const config = makeConfig();
- writeHintState(config, { lastHintShown: { claude: '2000-01-01T00:00:00.000Z' } });
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
+ yield* Effect.all(
+ Array.from({ length: 20 }, () =>
+ createPluginHint(config).showPluginHint(makeTerminal(output))
+ ),
+ { concurrency: 'unbounded' }
+ );
expect(output).toHaveLength(1);
+ expect(existsSync(join(config.stateDirectory, 'claude.stamp'))).toBe(true);
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('throttles Claude and Codex independently', () =>
+ it.effect('throttles each host independently', () =>
Effect.gen(function* () {
const claudeConfig = makeConfig({ host: 'claude' });
const codexConfig = makeConfig({ host: 'codex' });
+ yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
+ yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output));
yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output));
expect(output).toHaveLength(2);
- expect(output[0]).toContain('Claude Code');
- expect(output[1]).toContain('Codex');
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('honors the legacy global timestamp during state migration', () =>
- Effect.gen(function* () {
- const config = makeConfig({ host: 'codex' });
- writeFileAt(config.stateFile, JSON.stringify({ lastHintShown: new Date().toISOString() }));
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toEqual([]);
- }).pipe(Effect.provide(PlatformLayers))
- );
-
- it.effect('shows the hint when the throttle state file is unreadable', () =>
- Effect.gen(function* () {
- const config = makeConfig();
- writeFileAt(config.stateFile, 'not json{');
-
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
-
- expect(output).toHaveLength(1);
}).pipe(Effect.provide(PlatformLayers))
);
- it.effect('stamps the throttle state when the hint is shown', () =>
+ it.effect('retires a stale stamp and shows the hint again', () =>
Effect.gen(function* () {
+ vi.useFakeTimers();
+ vi.setSystemTime(new Date('2026-07-29T00:00:00.000Z'));
const config = makeConfig();
+ const stamp = join(config.stateDirectory, 'claude.stamp');
+ writeFileAt(stamp, '');
+ const stale = new Date('2026-07-27T00:00:00.000Z');
+ utimesSync(stamp, stale, stale);
yield* createPluginHint(config).showPluginHint(makeTerminal(output));
expect(output).toHaveLength(1);
- expect(existsSync(config.stateFile)).toBe(true);
- output = [];
- yield* createPluginHint(config).showPluginHint(makeTerminal(output));
- expect(output).toEqual([]);
}).pipe(Effect.provide(PlatformLayers))
);