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
feat(cli): agent-aware plugin acquisition hint (PRDE-1153)
Kshitij Jhunjhunwala9bfe6e3610c6
diff --git a/ts/packages/cli/CHANGELOG.md b/ts/packages/cli/CHANGELOG.mdindex 85d6306f3..0fce94532 100644--- a/ts/packages/cli/CHANGELOG.md+++ b/ts/packages/cli/CHANGELOG.md@@ -10,6 +10,7 @@### Minor Changes+- Cross-promote the Composio agent plugin (PRDE-1153): when the bare CLI runs inside Claude Code or Codex and the Composio plugin is not installed in that host, the CLI prints one stderr tip per 24 hours pointing at `composio setup`. The tip is deliberately visible to non-TTY (agent-driven) shells, never touches stdout, and is suppressed inside `composio run` children.- Make headless `composio login` agent-friendly (PRDE-1138): the non-interactive instructions now offer the unattended `composio login --agent` path, and a machine with a stored READY agent identity (`~/.composio/agent.json`) completes plain headless `composio login` unattended by reusing it. Reuse only — a human piping `composio login` still gets the URL + poll instructions and never has an account auto-created.- a0bef5d: Bump `@composio/client` to `0.1.0-alpha.74`.- 025a657: Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Node's native `require(esm)` interop, and the SDK no longer ships custom CommonJS compatibility machinery or `.cjs` artifacts.diff --git a/ts/packages/cli/src/cli-main.ts b/ts/packages/cli/src/cli-main.tsindex 6b672c525..1bd142fe9 100644--- a/ts/packages/cli/src/cli-main.ts+++ b/ts/packages/cli/src/cli-main.ts@@ -30,6 +30,7 @@ import { ProjectContext } from 'src/services/project-context';import { ProjectEnvironmentDetector } from 'src/services/project-environment-detector';import { CommandRunner } from 'src/services/command-runner';import { StdinLive } from 'src/services/stdin';+import { showPluginAcquisitionHint } from 'src/services/plugin-hint';import { showUpdateNotice } from 'src/services/update-check';import {createCliCommandTelemetryContext,@@ -174,6 +175,7 @@ const runWithTelemetry = Effect.gen(function* () {});showUpdateNotice.pipe(+ Effect.andThen(showPluginAcquisitionHint),Effect.andThen(runWithTelemetry),Effect.catchIf(ValidationError.isValidationError, error => {return Effect.gen(function* () {diff --git a/ts/packages/cli/src/services/plugin-hint.ts b/ts/packages/cli/src/services/plugin-hint.tsnew file mode 100644index 000000000..4bbadd52f--- /dev/null+++ b/ts/packages/cli/src/services/plugin-hint.ts@@ -0,0 +1,170 @@+import { FileSystem, Path } from '@effect/platform';+import { BunFileSystem } from '@effect/platform-bun';+import { Config, ConfigProvider, Effect, Layer, Option, Schema } from 'effect';+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.+ */++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;+ readonly codexThreadId: string | undefined;+ 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;+}++export interface PluginHintState {+ lastHintShown: string; // ISO-8601+}++const PluginHintStateSchema = Schema.parseJson(+ Schema.Struct({+ lastHintShown: Schema.String,+ })+);++const InstalledPluginsSchema = Schema.parseJson(+ Schema.Struct({+ plugins: Schema.Record({ key: Schema.String, value: Schema.Array(Schema.Unknown) }),+ })+);++export interface PluginHintConfig {+ readonly stateFile: string;+ readonly host: PluginHost | undefined;+ readonly invocationOrigin: 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 yield* Schema.decodeUnknown(PluginHintStateSchema)(rawState);+ });++ const writeState = Effect.gen(function* () {+ const fs = yield* FileSystem.FileSystem;+ const path = yield* Path.Path;+ const state: PluginHintState = { lastHintShown: new Date().toISOString() };+ yield* fs.makeDirectory(path.dirname(config.stateFile), { recursive: true });+ yield* fs.writeFileString(config.stateFile, JSON.stringify(state, null, 2));+ });++ const shownWithinInterval = (state: Option.Option<PluginHintState>): boolean => {+ if (Option.isNone(state)) return false;+ const shownAt = new Date(state.value.lastHintShown).getTime();+ if (!Number.isFinite(shownAt)) return false;+ return Date.now() - shownAt < config.hintIntervalMs;+ };++ // "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;+ 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 codexPluginAbsent = Effect.gen(function* () {+ const fs = yield* FileSystem.FileSystem;+ const fileExists = yield* fs.exists(config.codexConfigFile);+ if (!fileExists) return true;+ const raw = yield* fs.readFileString(config.codexConfigFile);+ return !raw.includes(`[plugins."${PLUGIN_ID}"]`);+ });++ const pluginAbsentByHost: Record<+ PluginHost,+ Effect.Effect<boolean, unknown, FileSystem.FileSystem>+ > = {+ claude: claudePluginAbsent,+ codex: codexPluginAbsent,+ };++ 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)) return;+ const absent = yield* pluginAbsentByHost[config.host];+ if (!absent) return;+ yield* writeState;+ const label = HOST_LABELS[config.host];+ yield* terminal.error(+ `Tip: running under ${label} without the Composio plugin — 'composio setup' installs it.`+ );+ }).pipe(Effect.ignore);+ }++ return { showPluginHint };+}++const DefaultConfigLayers = Layer.mergeAll(Path.layer, NodeOs.Default, BunFileSystem.layer);++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;+ const claudeCode = yield* readOptionalEnv('CLAUDECODE');+ const codexThreadId = yield* readOptionalEnv('CODEX_THREAD_ID');+ const codexSandbox = yield* readOptionalEnv('CODEX_SANDBOX');+ const invocationOrigin = yield* readOptionalEnv('COMPOSIO_CLI_INVOCATION_ORIGIN');+ 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 }),+ 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;+}).pipe(Effect.withConfigProvider(ConfigProvider.fromEnv()));++/** 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));diff --git a/ts/packages/cli/test/src/services/plugin-hint.test.ts b/ts/packages/cli/test/src/services/plugin-hint.test.tsnew file mode 100644index 000000000..527fea29c--- /dev/null+++ b/ts/packages/cli/test/src/services/plugin-hint.test.ts@@ -0,0 +1,278 @@+import { describe, it, expect, beforeEach, afterEach } from '@effect/vitest';+import { existsSync, mkdirSync, mkdtempSync, rmSync, 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 {+ createPluginHint,+ detectPluginHost,+ type PluginHintConfig,+ type PluginHintState,+} from 'src/services/plugin-hint';++const PlatformLayers = Layer.mergeAll(BunFileSystem.layer, BunPath.layer);++const DAY_MS = 24 * 60 * 60 * 1000;++let tempDir: string;+beforeEach(() => {+ tempDir = mkdtempSync(join(tmpdir(), 'plugin-hint-test-'));+});+afterEach(() => {+ rmSync(tempDir, { recursive: true, force: true });+});++function makeConfig(overrides?: Partial<PluginHintConfig>): PluginHintConfig {+ return {+ stateFile: join(tempDir, '.composio', 'plugin-hint.json'),+ host: 'claude',+ invocationOrigin: undefined,+ claudeInstalledPluginsFile: join(tempDir, '.claude', 'plugins', 'installed_plugins.json'),+ codexConfigFile: join(tempDir, '.codex', 'config.toml'),+ hintIntervalMs: DAY_MS,+ ...overrides,+ };+}++const makeTerminal = (output: string[]): Pick<TerminalUI, 'error'> => ({+ error: line => Effect.sync(() => output.push(line)),+});++function writeFileAt(file: string, contents: string): void {+ mkdirSync(dirname(file), { recursive: true });+ 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', () => {+ 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,+ codexThreadId: undefined,+ codexSandbox: 'seatbelt',+ })+ ).toBe('codex');+ });++ it('prefers Claude Code when both markers are present', () => {+ expect(+ detectPluginHost({ claudeCode: '1', codexThreadId: 'abc', codexSandbox: undefined })+ ).toBe('claude');+ });++ it('detects no host without markers', () => {+ expect(+ detectPluginHost({ claudeCode: undefined, codexThreadId: undefined, codexSandbox: undefined })+ ).toBeUndefined();+ });+});++describe('showPluginHint', () => {+ let output: string[];++ beforeEach(() => {+ output = [];+ });++ it.effect('shows the hint when the Claude plugin state file is missing', () =>+ Effect.gen(function* () {+ const config = makeConfig();++ yield* createPluginHint(config).showPluginHint(makeTerminal(output));++ expect(output).toHaveLength(1);+ 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);+ }).pipe(Effect.provide(PlatformLayers))+ );++ it.effect('stays silent when the Claude plugin is installed', () =>+ Effect.gen(function* () {+ const config = makeConfig();+ writeClaudePlugins(config, { 'composio@composio': [{ scope: 'user' }] });++ yield* createPluginHint(config).showPluginHint(makeTerminal(output));++ expect(output).toEqual([]);+ expect(existsSync(config.stateFile)).toBe(false);+ }).pipe(Effect.provide(PlatformLayers))+ );++ it.effect('stays silent when the Claude plugin state file is unreadable', () =>+ Effect.gen(function* () {+ const config = makeConfig();+ writeFileAt(config.claudeInstalledPluginsFile, 'not json{');++ yield* createPluginHint(config).showPluginHint(makeTerminal(output));++ expect(output).toEqual([]);+ }).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', () =>+ Effect.gen(function* () {+ const config = makeConfig({ host: undefined });++ 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));++ expect(output).toEqual([]);+ }).pipe(Effect.provide(PlatformLayers))+ );++ it.effect('stays silent when the hint was shown within the interval', () =>+ Effect.gen(function* () {+ const config = makeConfig();+ writeHintState(config, { lastHintShown: 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: '2000-01-01T00:00:00.000Z' });++ yield* createPluginHint(config).showPluginHint(makeTerminal(output));++ expect(output).toHaveLength(1);+ }).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', () =>+ Effect.gen(function* () {+ const config = makeConfig();++ 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))+ );++ it.effect('writes to stderr even when no stream is a TTY', () =>+ Effect.gen(function* () {+ const config = makeConfig();+ const chunks: string[] = [];+ const capture = new Writable({+ write(chunk, _encoding, callback) {+ chunks.push(String(chunk));+ callback();+ },+ });+ const terminal = makeTerminalUI({+ stdin: { isTTY: false },+ stdout: Object.assign(new Writable({ write: (_c, _e, cb) => cb() }), { isTTY: false }),+ stderr: Object.assign(capture, { isTTY: false }),+ });++ yield* createPluginHint(config).showPluginHint(terminal);++ expect(chunks.join('')).toContain('composio setup');+ }).pipe(Effect.provide(PlatformLayers))+ );+});