Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { describe, expect, it } from '@effect/vitest'; |
| 2 | import { afterEach, beforeEach, vi } from 'vitest'; |
| 3 | import * as BunServices from '@effect/platform-bun/BunServices'; |
| 4 | import { ConfigProvider, Effect, Layer } from 'effect'; |
| 5 | import { existsSync, mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from 'node:fs'; |
| 6 | import { tmpdir } from 'node:os'; |
| 7 | import { dirname, join } from 'node:path'; |
| 8 | import { Writable } from 'node:stream'; |
| 9 | import { HOST_CONFIG } from 'src/config'; |
| 10 | import { APP_VERSION } from 'src/constants'; |
| 11 | import { |
| 12 | CommandLifecycleTelemetry, |
| 13 | type PluginHintShown, |
| 14 | } from 'src/services/command-lifecycle-telemetry'; |
| 15 | import { defaultNodeOs, NodeOs } from 'src/services/node-os'; |
| 16 | import { NodeProcess } from 'src/services/node-process'; |
| 17 | import { detectPluginHost } from 'src/services/agent-host-env'; |
| 18 | import { |
| 19 | createPluginHint, |
| 20 | PluginHint, |
| 21 | resolvePluginHintConfig, |
| 22 | type PluginHintConfig, |
| 23 | } from 'src/services/plugin-hint'; |
| 24 | import { makeTerminalUI, TerminalUI } from 'src/services/terminal-ui'; |
| 25 | import { commandIdentity } from 'test/__utils__/command-identity'; |
| 26 | import { terminalUITestImpl } from 'test/__utils__/services/terminal-ui-test'; |
| 27 | import { trackedEvents } from 'test/__utils__/tracked-events'; |
| 28 | |
| 29 | vi.mock('src/analytics/dispatch', async importOriginal => { |
| 30 | const { recordTrackedEvent } = await import('test/__utils__/tracked-events'); |
| 31 | return { |
| 32 | ...(await importOriginal<typeof import('src/analytics/dispatch')>()), |
| 33 | trackCliEventEffect: recordTrackedEvent, |
| 34 | }; |
| 35 | }); |
| 36 | |
| 37 | const DAY_MS = 24 * 60 * 60 * 1000; |
| 38 | |
| 39 | let tempDir: string; |
| 40 | /** What the hint reported through `telemetry` in the current test. */ |
| 41 | let shownEvents: PluginHintShown[]; |
| 42 | const telemetry = { |
| 43 | pluginHintShown: (shown: PluginHintShown) => Effect.sync(() => shownEvents.push(shown)), |
| 44 | }; |
| 45 | beforeEach(() => { |
| 46 | tempDir = mkdtempSync(join(tmpdir(), 'plugin-hint-test-')); |
| 47 | shownEvents = []; |
| 48 | }); |
| 49 | afterEach(() => { |
| 50 | vi.useRealTimers(); |
| 51 | vi.unstubAllEnvs(); |
| 52 | trackedEvents.length = 0; |
| 53 | rmSync(tempDir, { recursive: true, force: true }); |
| 54 | }); |
| 55 | |
| 56 | const hintLayers = () => |
| 57 | Layer.mergeAll( |
| 58 | BunServices.layer, |
| 59 | NodeProcess.Default, |
| 60 | Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })), |
| 61 | Layer.succeed(TerminalUI, terminalUITestImpl) |
| 62 | ); |
| 63 | |
| 64 | function makeConfig(overrides?: Partial<PluginHintConfig>): PluginHintConfig { |
| 65 | return { |
| 66 | stateDirectory: join(tempDir, '.composio', 'plugin-hints'), |
| 67 | host: 'claude', |
| 68 | invocationOrigin: undefined, |
| 69 | commandPath: 'version', |
| 70 | claudeInstalledPluginsFile: join(tempDir, '.claude', 'plugins', 'installed_plugins.json'), |
| 71 | codexConfigFile: join(tempDir, '.codex', 'config.toml'), |
| 72 | hintIntervalMs: DAY_MS, |
| 73 | ...overrides, |
| 74 | }; |
| 75 | } |
| 76 | |
| 77 | const makeTerminal = (output: string[]): Pick<TerminalUI, 'error'> => ({ |
| 78 | error: line => Effect.sync(() => output.push(line)), |
| 79 | }); |
| 80 | |
| 81 | function writeFileAt(file: string, contents: string): void { |
| 82 | mkdirSync(dirname(file), { recursive: true }); |
| 83 | writeFileSync(file, contents); |
| 84 | } |
| 85 | |
| 86 | function writeClaudePlugins(config: PluginHintConfig, plugins: Record<string, unknown[]>): void { |
| 87 | writeFileAt(config.claudeInstalledPluginsFile, JSON.stringify({ version: 2, plugins })); |
| 88 | } |
| 89 | |
| 90 | describe('detectPluginHost', () => { |
| 91 | it('detects supported hosts from non-empty markers', () => { |
| 92 | expect( |
| 93 | detectPluginHost({ claudeCode: '1', codexThreadId: undefined, codexSandbox: undefined }) |
| 94 | ).toBe('claude'); |
| 95 | expect( |
| 96 | detectPluginHost({ claudeCode: undefined, codexThreadId: 'abc', codexSandbox: undefined }) |
| 97 | ).toBe('codex'); |
| 98 | expect( |
| 99 | detectPluginHost({ |
| 100 | claudeCode: undefined, |
| 101 | codexThreadId: undefined, |
| 102 | codexSandbox: 'seatbelt', |
| 103 | }) |
| 104 | ).toBe('codex'); |
| 105 | }); |
| 106 | |
| 107 | it('prefers Claude Code when both hosts have non-empty markers', () => { |
| 108 | expect( |
| 109 | detectPluginHost({ claudeCode: '1', codexThreadId: 'abc', codexSandbox: undefined }) |
| 110 | ).toBe('claude'); |
| 111 | }); |
| 112 | |
| 113 | it.effect('ignores empty and whitespace-only markers', () => |
| 114 | Effect.gen(function* () { |
| 115 | const markers = yield* HOST_CONFIG.AGENT_HOST.parse( |
| 116 | ConfigProvider.fromEnvRecord({ CLAUDECODE: '', CODEX_THREAD_ID: ' ', CODEX_SANDBOX: '\t' }) |
| 117 | ); |
| 118 | expect(detectPluginHost(markers)).toBeUndefined(); |
| 119 | }) |
| 120 | ); |
| 121 | }); |
| 122 | |
| 123 | describe('resolvePluginHintConfig', () => { |
| 124 | it.effect('stores throttle stamps under COMPOSIO_CACHE_DIR', () => { |
| 125 | const cacheDir = join(tempDir, 'writable-cache'); |
| 126 | vi.stubEnv('COMPOSIO_CACHE_DIR', cacheDir); |
| 127 | vi.stubEnv('CLAUDECODE', '1'); |
| 128 | |
| 129 | return Effect.gen(function* () { |
| 130 | const config = yield* resolvePluginHintConfig('version'); |
| 131 | |
| 132 | expect(config.stateDirectory).toBe(join(cacheDir, 'plugin-hints')); |
| 133 | expect(config.host).toBe('claude'); |
| 134 | expect(config.commandPath).toBe('version'); |
| 135 | }).pipe( |
| 136 | Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()), |
| 137 | Effect.provide(hintLayers()) |
| 138 | ); |
| 139 | }); |
| 140 | |
| 141 | it.effect('falls back to host defaults for blank path overrides', () => { |
| 142 | vi.stubEnv('CLAUDE_CONFIG_DIR', ''); |
| 143 | vi.stubEnv('CODEX_HOME', ' '); |
| 144 | |
| 145 | return Effect.gen(function* () { |
| 146 | const config = yield* resolvePluginHintConfig('version'); |
| 147 | |
| 148 | expect(config.claudeInstalledPluginsFile).toBe( |
| 149 | join(tempDir, '.claude', 'plugins', 'installed_plugins.json') |
| 150 | ); |
| 151 | expect(config.codexConfigFile).toBe(join(tempDir, '.codex', 'config.toml')); |
| 152 | }).pipe( |
| 153 | Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()), |
| 154 | Effect.provide(hintLayers()) |
| 155 | ); |
| 156 | }); |
| 157 | |
| 158 | it.effect('preserves nonblank path overrides', () => { |
| 159 | const claudeConfigDir = join(tempDir, 'claude profile'); |
| 160 | const codexHome = join(tempDir, 'codex profile'); |
| 161 | vi.stubEnv('CLAUDE_CONFIG_DIR', claudeConfigDir); |
| 162 | vi.stubEnv('CODEX_HOME', codexHome); |
| 163 | |
| 164 | return Effect.gen(function* () { |
| 165 | const config = yield* resolvePluginHintConfig('version'); |
| 166 | |
| 167 | expect(config.claudeInstalledPluginsFile).toBe( |
| 168 | join(claudeConfigDir, 'plugins', 'installed_plugins.json') |
| 169 | ); |
| 170 | expect(config.codexConfigFile).toBe(join(codexHome, 'config.toml')); |
| 171 | }).pipe( |
| 172 | Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()), |
| 173 | Effect.provide(hintLayers()) |
| 174 | ); |
| 175 | }); |
| 176 | |
| 177 | it.effect('anchors relative path overrides to the home directory', () => { |
| 178 | vi.stubEnv('CLAUDE_CONFIG_DIR', 'claude-relative'); |
| 179 | vi.stubEnv('CODEX_HOME', 'codex-relative'); |
| 180 | |
| 181 | return Effect.gen(function* () { |
| 182 | const config = yield* resolvePluginHintConfig('version'); |
| 183 | |
| 184 | expect(config.claudeInstalledPluginsFile).toBe( |
| 185 | join(tempDir, 'claude-relative', 'plugins', 'installed_plugins.json') |
| 186 | ); |
| 187 | expect(config.codexConfigFile).toBe(join(tempDir, 'codex-relative', 'config.toml')); |
| 188 | }).pipe( |
| 189 | Effect.provideService(ConfigProvider.ConfigProvider, ConfigProvider.fromEnv()), |
| 190 | Effect.provide(hintLayers()) |
| 191 | ); |
| 192 | }); |
| 193 | }); |
| 194 | |
| 195 | describe('showPluginHint', () => { |
| 196 | let output: string[]; |
| 197 | |
| 198 | beforeEach(() => { |
| 199 | output = []; |
| 200 | }); |
| 201 | |
| 202 | it.effect('shows the hint when a host plugin is confidently absent', () => |
| 203 | Effect.gen(function* () { |
| 204 | const claudeConfig = makeConfig(); |
| 205 | writeClaudePlugins(claudeConfig, { 'other@marketplace': [{ scope: 'user' }] }); |
| 206 | yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry); |
| 207 | |
| 208 | const codexConfig = makeConfig({ host: 'codex' }); |
| 209 | writeFileAt(codexConfig.codexConfigFile, '[plugins."glen@glen"]\nenabled = true\n'); |
| 210 | yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry); |
| 211 | |
| 212 | expect(output).toEqual([ |
| 213 | "Tip: running under Claude Code without the Composio plugin — 'composio setup --yes' installs it.", |
| 214 | "Tip: running under Codex without the Composio plugin — 'composio setup --yes' installs it.", |
| 215 | ]); |
| 216 | }).pipe(Effect.provide(hintLayers())) |
| 217 | ); |
| 218 | |
| 219 | it.effect('releases the claim when printing fails so the next run can retry', () => |
| 220 | Effect.gen(function* () { |
| 221 | const config = makeConfig(); |
| 222 | |
| 223 | yield* createPluginHint(config).showPluginHint( |
| 224 | { error: () => Effect.die(new Error('EPIPE')) }, |
| 225 | telemetry |
| 226 | ); |
| 227 | expect(existsSync(join(config.stateDirectory, 'claude.stamp'))).toBe(false); |
| 228 | |
| 229 | yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry); |
| 230 | expect(output).toHaveLength(1); |
| 231 | }).pipe(Effect.provide(hintLayers())) |
| 232 | ); |
| 233 | |
| 234 | it.effect('reports the hint to the telemetry service once per printed hint', () => |
| 235 | Effect.gen(function* () { |
| 236 | const config = makeConfig({ invocationOrigin: 'installer', commandPath: 'whoami' }); |
| 237 | |
| 238 | yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry); |
| 239 | yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry); |
| 240 | |
| 241 | expect(output).toHaveLength(1); |
| 242 | expect(shownEvents).toEqual([ |
| 243 | { invocationOrigin: 'installer', commandPath: 'whoami', agentHost: 'claude' }, |
| 244 | ]); |
| 245 | // The hint tracks nothing itself. |
| 246 | expect(trackedEvents).toEqual([]); |
| 247 | }).pipe(Effect.provide(hintLayers())) |
| 248 | ); |
| 249 | |
| 250 | it.effect('stays silent when the plugin is installed', () => |
| 251 | Effect.gen(function* () { |
| 252 | const claudeConfig = makeConfig(); |
| 253 | writeClaudePlugins(claudeConfig, { 'composio@composio': [{ scope: 'user' }] }); |
| 254 | yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry); |
| 255 | |
| 256 | const codexConfig = makeConfig({ host: 'codex' }); |
| 257 | writeFileAt(codexConfig.codexConfigFile, '[plugins."composio@composio"]\nenabled = true\n'); |
| 258 | yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry); |
| 259 | |
| 260 | expect(output).toEqual([]); |
| 261 | expect(existsSync(claudeConfig.stateDirectory)).toBe(false); |
| 262 | }).pipe(Effect.provide(hintLayers())) |
| 263 | ); |
| 264 | |
| 265 | it.effect('stays silent when plugin state is unreadable', () => |
| 266 | Effect.gen(function* () { |
| 267 | const config = makeConfig(); |
| 268 | writeFileAt(config.claudeInstalledPluginsFile, 'not json{'); |
| 269 | |
| 270 | yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry); |
| 271 | |
| 272 | expect(output).toEqual([]); |
| 273 | }).pipe(Effect.provide(hintLayers())) |
| 274 | ); |
| 275 | |
| 276 | // `composio setup` turns the hint off in its `CommandMeta`; see |
| 277 | // `test/src/invocation/invocation-hooks.test.ts`. |
| 278 | it.effect('stays silent outside a host and in run children', () => |
| 279 | Effect.gen(function* () { |
| 280 | const configs = [makeConfig({ host: undefined }), makeConfig({ invocationOrigin: 'run' })]; |
| 281 | |
| 282 | yield* Effect.forEach(configs, config => |
| 283 | createPluginHint(config).showPluginHint(makeTerminal(output), telemetry) |
| 284 | ); |
| 285 | |
| 286 | expect(output).toEqual([]); |
| 287 | expect(shownEvents).toEqual([]); |
| 288 | expect(existsSync(configs[1]!.stateDirectory)).toBe(false); |
| 289 | }).pipe(Effect.provide(hintLayers())) |
| 290 | ); |
| 291 | |
| 292 | it.effect('allows only one concurrent process to claim a host hint', () => |
| 293 | Effect.gen(function* () { |
| 294 | const config = makeConfig(); |
| 295 | |
| 296 | yield* Effect.all( |
| 297 | Array.from({ length: 20 }, () => |
| 298 | createPluginHint(config).showPluginHint(makeTerminal(output), telemetry) |
| 299 | ), |
| 300 | { concurrency: 'unbounded' } |
| 301 | ); |
| 302 | |
| 303 | expect(output).toHaveLength(1); |
| 304 | expect(existsSync(join(config.stateDirectory, 'claude.stamp'))).toBe(true); |
| 305 | }).pipe(Effect.provide(hintLayers())) |
| 306 | ); |
| 307 | |
| 308 | it.effect('throttles each host independently', () => |
| 309 | Effect.gen(function* () { |
| 310 | const claudeConfig = makeConfig({ host: 'claude' }); |
| 311 | const codexConfig = makeConfig({ host: 'codex' }); |
| 312 | |
| 313 | yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry); |
| 314 | yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry); |
| 315 | yield* createPluginHint(claudeConfig).showPluginHint(makeTerminal(output), telemetry); |
| 316 | yield* createPluginHint(codexConfig).showPluginHint(makeTerminal(output), telemetry); |
| 317 | |
| 318 | expect(output).toHaveLength(2); |
| 319 | }).pipe(Effect.provide(hintLayers())) |
| 320 | ); |
| 321 | |
| 322 | it.effect('retires a stale stamp and shows the hint again', () => |
| 323 | Effect.gen(function* () { |
| 324 | vi.useFakeTimers(); |
| 325 | vi.setSystemTime(new Date('2026-07-29T00:00:00.000Z')); |
| 326 | const config = makeConfig(); |
| 327 | const stamp = join(config.stateDirectory, 'claude.stamp'); |
| 328 | writeFileAt(stamp, ''); |
| 329 | const stale = new Date('2026-07-27T00:00:00.000Z'); |
| 330 | utimesSync(stamp, stale, stale); |
| 331 | |
| 332 | yield* createPluginHint(config).showPluginHint(makeTerminal(output), telemetry); |
| 333 | |
| 334 | expect(output).toHaveLength(1); |
| 335 | }).pipe(Effect.provide(hintLayers())) |
| 336 | ); |
| 337 | |
| 338 | it.effect('writes to stderr even when no stream is a TTY', () => |
| 339 | Effect.gen(function* () { |
| 340 | const config = makeConfig(); |
| 341 | const chunks: string[] = []; |
| 342 | const capture = new Writable({ |
| 343 | write(chunk, _encoding, callback) { |
| 344 | chunks.push(String(chunk)); |
| 345 | callback(); |
| 346 | }, |
| 347 | }); |
| 348 | const terminal = makeTerminalUI({ |
| 349 | stdin: { isTTY: false }, |
| 350 | stdout: Object.assign(new Writable({ write: (_c, _e, cb) => cb() }), { isTTY: false }), |
| 351 | stderr: Object.assign(capture, { isTTY: false }), |
| 352 | }); |
| 353 | |
| 354 | yield* createPluginHint(config).showPluginHint(terminal, telemetry); |
| 355 | |
| 356 | expect(chunks.join('')).toContain('composio setup'); |
| 357 | }).pipe(Effect.provide(hintLayers())) |
| 358 | ); |
| 359 | }); |
| 360 | |
| 361 | describe('PluginHint', () => { |
| 362 | /** |
| 363 | * `PluginHint.Default` over the real `CommandLifecycleTelemetry` (its dispatcher mocked above), |
| 364 | * with every path under `tempDir` and a recording stderr. |
| 365 | */ |
| 366 | const pluginHintLayer = (output: string[]) => { |
| 367 | const services = Layer.mergeAll( |
| 368 | BunServices.layer, |
| 369 | Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempDir })), |
| 370 | Layer.succeed(TerminalUI, TerminalUI.of({ ...terminalUITestImpl, ...makeTerminal(output) })) |
| 371 | ); |
| 372 | return Layer.provide( |
| 373 | PluginHint.Default, |
| 374 | Layer.merge(services, Layer.provide(CommandLifecycleTelemetry.Default, services)) |
| 375 | ); |
| 376 | }; |
| 377 | |
| 378 | /** Runs under Claude Code, which has no Composio plugin installed. */ |
| 379 | const underClaudeCode = Effect.provideService( |
| 380 | ConfigProvider.ConfigProvider, |
| 381 | ConfigProvider.fromEnvRecord({ CLAUDECODE: '1' }) |
| 382 | ); |
| 383 | |
| 384 | it.effect( |
| 385 | '[Given] Claude Code without the plugin [Then] prints the hint once per interval and tracks it through the telemetry service', |
| 386 | () => { |
| 387 | const output: string[] = []; |
| 388 | const identity = commandIdentity(['dev', 'triggers', 'list']); |
| 389 | return Effect.gen(function* () { |
| 390 | const hint = yield* PluginHint; |
| 391 | yield* hint.run({ identity }); |
| 392 | yield* hint.run({ identity }); |
| 393 | |
| 394 | expect(output).toEqual([ |
| 395 | "Tip: running under Claude Code without the Composio plugin — 'composio setup --yes' installs it.", |
| 396 | ]); |
| 397 | expect(trackedEvents).toEqual([ |
| 398 | { |
| 399 | name: 'CLI_PLUGIN_HINT_SHOWN', |
| 400 | properties: expect.objectContaining({ |
| 401 | source: 'cli', |
| 402 | invocation_origin: 'cli', |
| 403 | cli_version: APP_VERSION, |
| 404 | command_path: 'dev triggers list', |
| 405 | agent_host: 'claude', |
| 406 | }), |
| 407 | }, |
| 408 | ]); |
| 409 | }).pipe(underClaudeCode, Effect.provide(pluginHintLayer(output))); |
| 410 | } |
| 411 | ); |
| 412 | }); |