Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
fix(cli): simplify and harden plugin hints
Kshitij Jhunjhunwalaaf772565f7fc
diff --git a/mise.lock b/mise.lockindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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.tsindex 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, BunFileSyconst 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.tsindex 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.tsindex 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)));