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 * as FileSystem from 'effect/FileSystem'; |
| 2 | import * as Path from 'effect/Path'; |
| 3 | import { Context, Effect, Exit, Layer, Option, Schema } from 'effect'; |
| 4 | import { APP_CONFIG } from 'src/config'; |
| 5 | import { captureServices } from 'src/effects/capture-services'; |
| 6 | import { setupCacheDir } from 'src/effects/setup-cache-dir'; |
| 7 | import { commandPathOf } from 'src/invocation/command-identity'; |
| 8 | import { AGENT_HOST_LABELS, COMPOSIO_AGENT_PLUGIN_ID, type AgentHost } from './agent-host'; |
| 9 | import { detectPluginHost, hostConfigDirectory, rawHostEnvironment } from './agent-host-env'; |
| 10 | import { |
| 11 | CommandLifecycleTelemetry, |
| 12 | type CommandLifecycleTelemetryShape, |
| 13 | } from './command-lifecycle-telemetry'; |
| 14 | import { NodeOs } from './node-os'; |
| 15 | import type { InvocationHookShape } from './invocation-hook'; |
| 16 | import { DEFAULT_CLI_INVOCATION_ORIGIN } from './runtime-cli-context'; |
| 17 | import { TerminalUI } from './terminal-ui'; |
| 18 | |
| 19 | /** |
| 20 | * One-line acquisition hint for the Composio agent plugin. |
| 21 | * |
| 22 | * The primary audience is the agent driving the CLI through a non-TTY shell, |
| 23 | * so this line is intentionally not gated on stderr being a TTY. `composio setup`, which |
| 24 | * installs the plugin, turns it off in its `CommandMeta`. |
| 25 | */ |
| 26 | |
| 27 | const HINT_INTERVAL_MS = 24 * 60 * 60 * 1000; |
| 28 | |
| 29 | const InstalledPluginsSchema = Schema.fromJsonString( |
| 30 | Schema.Struct({ |
| 31 | plugins: Schema.Record(Schema.String, Schema.Array(Schema.Unknown)), |
| 32 | }) |
| 33 | ); |
| 34 | |
| 35 | export interface PluginHintConfig { |
| 36 | readonly stateDirectory: string; |
| 37 | readonly host: AgentHost | undefined; |
| 38 | readonly invocationOrigin: string | undefined; |
| 39 | /** The command the hint is shown for, as telemetry records it (`commandPathOf`). */ |
| 40 | readonly commandPath: string; |
| 41 | readonly claudeInstalledPluginsFile: string; |
| 42 | readonly codexConfigFile: string; |
| 43 | readonly hintIntervalMs: number; |
| 44 | } |
| 45 | |
| 46 | export function createPluginHint(config: PluginHintConfig) { |
| 47 | const claimHint = (host: AgentHost) => |
| 48 | Effect.gen(function* () { |
| 49 | const fs = yield* FileSystem.FileSystem; |
| 50 | const path = yield* Path.Path; |
| 51 | const stampPath = path.join(config.stateDirectory, `${host}.stamp`); |
| 52 | yield* fs.makeDirectory(config.stateDirectory, { recursive: true }); |
| 53 | |
| 54 | const stampInfo = yield* Effect.option(fs.stat(stampPath)); |
| 55 | if (Option.isSome(stampInfo)) { |
| 56 | const shownAt = Option.getOrUndefined(stampInfo.value.mtime)?.getTime(); |
| 57 | if ( |
| 58 | shownAt !== undefined && |
| 59 | Number.isFinite(shownAt) && |
| 60 | Date.now() - shownAt < config.hintIntervalMs |
| 61 | ) { |
| 62 | return false; |
| 63 | } |
| 64 | |
| 65 | // Retiring via rename means only one concurrent process can replace a |
| 66 | // stale stamp. Everyone else either sees the new stamp or loses the |
| 67 | // exclusive create below. |
| 68 | const retiredPath = `${stampPath}.${crypto.randomUUID()}`; |
| 69 | const retired = yield* Effect.option(fs.rename(stampPath, retiredPath)); |
| 70 | yield* fs.remove(retiredPath, { force: true }).pipe(Effect.ignore); |
| 71 | if (Option.isNone(retired)) return false; |
| 72 | } |
| 73 | |
| 74 | return yield* Effect.scoped(fs.open(stampPath, { flag: 'wx' })).pipe( |
| 75 | Effect.as(true), |
| 76 | Effect.orElseSucceed(() => false) |
| 77 | ); |
| 78 | }).pipe(Effect.orElseSucceed(() => false)); |
| 79 | |
| 80 | const releaseHint = (host: AgentHost) => |
| 81 | Effect.gen(function* () { |
| 82 | const fs = yield* FileSystem.FileSystem; |
| 83 | const path = yield* Path.Path; |
| 84 | yield* fs.remove(path.join(config.stateDirectory, `${host}.stamp`), { force: true }); |
| 85 | }).pipe(Effect.ignore); |
| 86 | |
| 87 | // "Confidently absent" only: a missing state file means the plugin was never |
| 88 | // installed, while an unreadable or unrecognized one suppresses the hint. |
| 89 | const claudePluginAbsent = Effect.gen(function* () { |
| 90 | const fs = yield* FileSystem.FileSystem; |
| 91 | if (!(yield* fs.exists(config.claudeInstalledPluginsFile))) return true; |
| 92 | const raw = yield* fs.readFileString(config.claudeInstalledPluginsFile); |
| 93 | const decoded = yield* Effect.option(Schema.decodeUnknownEffect(InstalledPluginsSchema)(raw)); |
| 94 | if (Option.isNone(decoded)) return false; |
| 95 | const installs = decoded.value.plugins[COMPOSIO_AGENT_PLUGIN_ID]; |
| 96 | return installs === undefined || installs.length === 0; |
| 97 | }); |
| 98 | |
| 99 | const codexPluginAbsent = Effect.gen(function* () { |
| 100 | const fs = yield* FileSystem.FileSystem; |
| 101 | if (!(yield* fs.exists(config.codexConfigFile))) return true; |
| 102 | const raw = yield* fs.readFileString(config.codexConfigFile); |
| 103 | return !raw.includes(`[plugins."${COMPOSIO_AGENT_PLUGIN_ID}"]`); |
| 104 | }); |
| 105 | |
| 106 | const pluginAbsentByHost: Readonly< |
| 107 | Record<AgentHost, Effect.Effect<boolean, unknown, FileSystem.FileSystem>> |
| 108 | > = { |
| 109 | claude: claudePluginAbsent, |
| 110 | codex: codexPluginAbsent, |
| 111 | }; |
| 112 | |
| 113 | function showPluginHint( |
| 114 | terminal: Pick<TerminalUI, 'error'>, |
| 115 | telemetry: Pick<CommandLifecycleTelemetryShape, 'pluginHintShown'> |
| 116 | ) { |
| 117 | return Effect.gen(function* () { |
| 118 | const host = config.host; |
| 119 | if (host === undefined || config.invocationOrigin === 'run') { |
| 120 | return; |
| 121 | } |
| 122 | if (!(yield* pluginAbsentByHost[host])) return; |
| 123 | if (!(yield* claimHint(host))) return; |
| 124 | // The stamp must not outlive a failed delivery: if printing the hint |
| 125 | // does not succeed, release the claim so the next invocation can |
| 126 | // retry instead of staying muted for the full interval. Tracking |
| 127 | // below is best-effort by contract (the telemetry sink never |
| 128 | // fails), so a delivered hint with a lost event is accepted. |
| 129 | const printed = yield* Effect.exit( |
| 130 | terminal.error( |
| 131 | `Tip: running under ${AGENT_HOST_LABELS[host]} without the Composio plugin — 'composio setup --yes' installs it.` |
| 132 | ) |
| 133 | ); |
| 134 | if (Exit.isFailure(printed)) { |
| 135 | yield* releaseHint(host); |
| 136 | return; |
| 137 | } |
| 138 | yield* telemetry.pluginHintShown({ |
| 139 | invocationOrigin: config.invocationOrigin ?? DEFAULT_CLI_INVOCATION_ORIGIN, |
| 140 | commandPath: config.commandPath, |
| 141 | agentHost: host, |
| 142 | }); |
| 143 | }).pipe(Effect.ignore); |
| 144 | } |
| 145 | |
| 146 | return { showPluginHint }; |
| 147 | } |
| 148 | |
| 149 | export const resolvePluginHintConfig = (commandPath: string) => |
| 150 | Effect.gen(function* () { |
| 151 | const path = yield* Path.Path; |
| 152 | const cacheDir = yield* setupCacheDir; |
| 153 | const invocationOrigin = yield* APP_CONFIG.CLI_INVOCATION_ORIGIN; |
| 154 | const env = yield* rawHostEnvironment; |
| 155 | const claudeConfigDir = yield* hostConfigDirectory('claude'); |
| 156 | const codexConfigDir = yield* hostConfigDirectory('codex'); |
| 157 | return { |
| 158 | stateDirectory: path.join(cacheDir, 'plugin-hints'), |
| 159 | host: detectPluginHost(env), |
| 160 | invocationOrigin, |
| 161 | commandPath, |
| 162 | claudeInstalledPluginsFile: path.join(claudeConfigDir, 'plugins', 'installed_plugins.json'), |
| 163 | codexConfigFile: path.join(codexConfigDir, 'config.toml'), |
| 164 | hintIntervalMs: HINT_INTERVAL_MS, |
| 165 | } satisfies PluginHintConfig; |
| 166 | }); |
| 167 | |
| 168 | export type PluginHintShape = InvocationHookShape; |
| 169 | |
| 170 | /** |
| 171 | * Prints the plugin acquisition hint when eligible, and reports that it was shown through |
| 172 | * `CommandLifecycleTelemetry`. Never fails, never blocks on network. |
| 173 | */ |
| 174 | export class PluginHint extends Context.Service<PluginHint, PluginHintShape>()( |
| 175 | 'services/PluginHint' |
| 176 | ) { |
| 177 | static readonly Default: Layer.Layer< |
| 178 | PluginHint, |
| 179 | never, |
| 180 | TerminalUI | CommandLifecycleTelemetry | FileSystem.FileSystem | Path.Path | NodeOs |
| 181 | > = Layer.effect( |
| 182 | PluginHint, |
| 183 | Effect.gen(function* () { |
| 184 | const terminal = yield* TerminalUI; |
| 185 | const telemetry = yield* CommandLifecycleTelemetry; |
| 186 | const services = yield* captureServices(FileSystem.FileSystem, Path.Path, NodeOs, TerminalUI); |
| 187 | return PluginHint.of({ |
| 188 | run: ({ identity }) => |
| 189 | Effect.gen(function* () { |
| 190 | const config = yield* resolvePluginHintConfig(commandPathOf(identity)); |
| 191 | yield* createPluginHint(config).showPluginHint(terminal, telemetry); |
| 192 | }).pipe( |
| 193 | Effect.provideContext(services), |
| 194 | // The hint is advisory: a configuration it cannot read shows no hint. |
| 195 | Effect.ignore |
| 196 | ), |
| 197 | }); |
| 198 | }) |
| 199 | ); |
| 200 | } |