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.

Support listening to top-level composio events (#3125)

Rahul Tarak686f5a9470dc
diff --git a/ts/packages/cli/src/analytics/dispatch.ts b/ts/packages/cli/src/analytics/dispatch.ts
index 822844b8f..d205b4c5b 100644
--- a/ts/packages/cli/src/analytics/dispatch.ts
+++ b/ts/packages/cli/src/analytics/dispatch.ts
@@ -212,12 +212,12 @@ export const getCurrentCwdSessionId = (): string | undefined => {
const withCliSessionId = (event: TrackEvent): TrackEvent => {
if (!event) return event;
const cliSessionId = getCurrentCwdSessionId();
- if (!cliSessionId) return event;
return {
...event,
properties: {
...(event.properties ?? {}),
- cli_session_id: cliSessionId,
+ cli_version: event.properties?.cli_version ?? constants.APP_VERSION,
+ ...(cliSessionId ? { cli_session_id: cliSessionId } : {}),
},
};
};
diff --git a/ts/packages/cli/src/commands/listen.cmd.ts b/ts/packages/cli/src/commands/listen.cmd.ts
index 956705489..a48f1a2bc 100644
--- a/ts/packages/cli/src/commands/listen.cmd.ts
+++ b/ts/packages/cli/src/commands/listen.cmd.ts
@@ -1,5 +1,6 @@
import { Args, Command, Options } from '@effect/cli';
import { FileSystem } from '@effect/platform';
+import type { Composio as RawComposioClient } from '@composio/client';
import { Deferred, Effect, Option, Runtime } from 'effect';
import path from 'node:path';
import { requireAuth } from 'src/effects/require-auth';
@@ -21,17 +22,21 @@ import { matchesTriggerListenFilters } from './triggers/filter';
import { parseTriggerListenEvent } from './triggers/parse';
const slug = Args.text({ name: 'slug' }).pipe(
- Args.withDescription('Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE")')
+ Args.withDescription(
+ 'Trigger slug (e.g. "GMAIL_NEW_GMAIL_MESSAGE") or project event type (e.g. "composio.connected_account.expired")'
+ )
);
const params = Options.text('params').pipe(
Options.withAlias('p'),
- Options.withDescription('Trigger create params as JSON/JS object, @file, or - for stdin'),
+ Options.withDescription(
+ 'Trigger create params as JSON/JS object, @file, or - for stdin. Only valid for trigger slugs.'
+ ),
Options.optional
);
const maxEvents = Options.integer('max-events').pipe(
- Options.withDescription('Stop after receiving N events for this temporary trigger'),
+ Options.withDescription('Stop after receiving N matching events'),
Options.optional
);
@@ -57,6 +62,8 @@ const debug = Options.boolean('debug').pipe(
const sanitizePathPart = (value: string): string =>
value.replace(/[^A-Z0-9._-]+/gi, '-').replace(/^-+|-+$/g, '') || 'unknown';
+const isProjectEventType = (value: string): boolean => value.startsWith('composio.');
+
const resolveParamsInput = (input: Option.Option<string>) =>
resolveOptionalTextInput(input, { missingValue: '{}' });
@@ -79,6 +86,58 @@ const parseCreateParams = (raw: string) =>
return parsed as Record<string, unknown>;
});
+const assertSupportedListenParams = (params: {
+ listeningToProjectEvent: boolean;
+ slug: string;
+ createParamsInput: Record<string, unknown>;
+}) =>
+ params.listeningToProjectEvent && Object.keys(params.createParamsInput).length > 0
+ ? Effect.fail(
+ new Error(
+ `--params is only supported for trigger slugs. "${params.slug}" is a project-level composio.* event type and does not create a temporary trigger.`
+ )
+ )
+ : Effect.void;
+
+const resolveConnectedAccountIdForTrigger = (params: {
+ client: RawComposioClient;
+ slug: string;
+ consumerUserId: string;
+}) =>
+ Effect.gen(function* () {
+ const toolkitSlug = toolkitFromToolSlug(params.slug);
+ if (!toolkitSlug) {
+ return yield* Effect.fail(
+ new Error(
+ `Could not infer a toolkit from trigger slug "${params.slug}". Use a standard trigger slug such as "GMAIL_NEW_GMAIL_MESSAGE", or a project event type such as "composio.connected_account.expired".`
+ )
+ );
+ }
+
+ const connectedAccounts = yield* Effect.tryPromise({
+ try: () =>
+ params.client.connectedAccounts.list({
+ toolkit_slugs: [toolkitSlug],
+ user_ids: [params.consumerUserId],
+ statuses: ['ACTIVE'],
+ limit: 100,
+ }),
+ catch: error =>
+ new Error(`Failed to list connected accounts for "${toolkitSlug}": ${String(error)}`),
+ });
+ const connectedAccountId = selectConnectedAccountId(connectedAccounts.items);
+
+ if (!connectedAccountId) {
+ return yield* Effect.fail(
+ new Error(
+ `No active connected account found for toolkit "${toolkitSlug}" and consumer user "${params.consumerUserId}". Run \`composio link ${toolkitSlug}\` first.`
+ )
+ );
+ }
+
+ return connectedAccountId;
+ });
+
const selectConnectedAccountId = (
items: ReadonlyArray<{
id: string;
@@ -102,6 +161,9 @@ const emitStreamLine = (line: string, ui: TerminalUI) =>
yield* ui.output(line, { force: true });
});
+const eventTypeOf = (eventData: Record<string, unknown>): string | undefined =>
+ typeof eventData.type === 'string' && eventData.type.length > 0 ? eventData.type : undefined;
+
const extractEventFileId = (eventData: Record<string, unknown>): string => {
const candidates = [
eventData.id,
@@ -180,6 +242,23 @@ const formatStreamValue = (value: unknown): string => {
return JSON.stringify(value);
};
+const formatStopMessage = (params: {
+ matchingEvents: number;
+ timedOut: boolean;
+ temporaryTriggerDisabled: boolean;
+}): string => {
+ const eventLabel = `event${params.matchingEvents === 1 ? '' : 's'}`;
+ if (params.timedOut) {
+ return params.temporaryTriggerDisabled
+ ? `Stopped after timeout with ${params.matchingEvents} matching ${eventLabel}. Temporary trigger disabled.`
+ : `Stopped after timeout with ${params.matchingEvents} matching ${eventLabel}.`;
+ }
+
+ return params.temporaryTriggerDisabled
+ ? `Stopped after receiving ${params.matchingEvents} ${eventLabel}. Temporary trigger disabled.`
+ : `Stopped after receiving ${params.matchingEvents} ${eventLabel}.`;
+};
+
const TIMEOUT_UNITS_MS: Record<string, number> = {
ms: 1,
millisecond: 1,
@@ -252,44 +331,27 @@ export const listenCmd = Command.make(
);
}
+ const listeningToProjectEvent = isProjectEventType(slug);
const rawParams = Option.isSome(params)
? (yield* resolveParamsInput(params))?.trim() || '{}'
: '{}';
const createParamsInput = yield* parseCreateParams(rawParams);
- const toolkitSlug = toolkitFromToolSlug(slug);
- if (!toolkitSlug) {
- return yield* Effect.fail(
- new Error(
- `Could not infer a toolkit from trigger slug "${slug}". Use a standard trigger slug such as "GMAIL_NEW_GMAIL_MESSAGE".`
- )
- );
- }
-
- const connectedAccounts = yield* Effect.tryPromise({
- try: () =>
- client.connectedAccounts.list({
- toolkit_slugs: [toolkitSlug],
- user_ids: resolvedProject.consumerUserId ? [resolvedProject.consumerUserId] : undefined,
- statuses: ['ACTIVE'],
- limit: 100,
- }),
- catch: error =>
- new Error(`Failed to list connected accounts for "${toolkitSlug}": ${String(error)}`),
- });
- const resolvedConnectedAccountId = selectConnectedAccountId(connectedAccounts.items);
-
- if (!resolvedConnectedAccountId) {
- return yield* Effect.fail(
- new Error(
- `No active connected account found for toolkit "${toolkitSlug}" and consumer user "${resolvedProject.consumerUserId}". Run \`composio link ${toolkitSlug}\` first.`
- )
- );
- }
-
- const createParams = {
- ...createParamsInput,
- connected_account_id: resolvedConnectedAccountId,
- } as Parameters<typeof client.triggerInstances.upsert>[1];
+ yield* assertSupportedListenParams({ listeningToProjectEvent, slug, createParamsInput });
+
+ const resolvedConnectedAccountId = listeningToProjectEvent
+ ? undefined
+ : yield* resolveConnectedAccountIdForTrigger({
+ client,
+ slug,
+ consumerUserId: resolvedProject.consumerUserId,
+ });
+
+ const createParams = listeningToProjectEvent
+ ? undefined
+ : ({
+ ...createParamsInput,
+ connected_account_id: resolvedConnectedAccountId,
+ } as Parameters<typeof client.triggerInstances.upsert>[1]);
const timeoutMs = Option.match(timeout, {
onNone: () => undefined,
onSome: value => parseTimeoutMs(value),
@@ -311,7 +373,11 @@ export const listenCmd = Command.make(
onNone: () => resolveFallbackArtifactsDir(),
onSome: value => value.directoryPath,
});
- const triggerDir = path.join(artifactsRoot, 'triggers', sanitizePathPart(slug));
+ const triggerDir = path.join(
+ artifactsRoot,
+ listeningToProjectEvent ? 'events' : 'triggers',
+ sanitizePathPart(slug)
+ );
const streamFilePath = path.join(triggerDir, 'events.jsonl');
yield* fs.makeDirectory(triggerDir, { recursive: true });
@@ -323,21 +389,28 @@ export const listenCmd = Command.make(
const seenEventIds = new Set<string>();
yield* Effect.acquireUseRelease(
- Effect.tryPromise({
- try: () => client.triggerInstances.upsert(slug, createParams),
- catch: error =>
- new Error(`Failed to create temporary trigger "${slug}": ${String(error)}`),
- }),
+ listeningToProjectEvent
+ ? Effect.succeed<null | { trigger_id: string }>(null)
+ : Effect.tryPromise({
+ try: () => client.triggerInstances.upsert(slug, createParams),
+ catch: error =>
+ new Error(`Failed to create temporary trigger "${slug}": ${String(error)}`),
+ }),
createdTrigger =>
Effect.gen(function* () {
yield* emitStreamLine(`listening for events ${slug} (tail at ${streamFilePath})`, ui);
if (debug) {
- const debugMsg = `[debug] trigger_id=${createdTrigger.trigger_id} project=${resolvedProject.projectId} org=${resolvedProject.orgId} createParams=${JSON.stringify(createParams)}`;
+ const debugMsg =
+ createdTrigger === null
+ ? `[debug] event_type=${slug} project=${resolvedProject.projectId} org=${resolvedProject.orgId}`
+ : `[debug] trigger_id=${createdTrigger.trigger_id} project=${resolvedProject.projectId} org=${resolvedProject.orgId} createParams=${JSON.stringify(createParams)}`;
yield* emitStreamLine(debugMsg, ui);
- yield* emitStreamLine(
- `[debug] upsert response: ${JSON.stringify(createdTrigger)}`,
- ui
- );
+ if (createdTrigger !== null) {
+ yield* emitStreamLine(
+ `[debug] upsert response: ${JSON.stringify(createdTrigger)}`,
+ ui
+ );
+ }
}
const onEvent = (eventData: Record<string, unknown>) => {
@@ -353,14 +426,20 @@ export const listenCmd = Command.make(
ui
);
}
- const parsed = parseTriggerListenEvent(eventData);
- const filterResult = matchesTriggerListenFilters(
- { triggerId: createdTrigger.trigger_id },
- parsed
- );
+ const parsedTriggerEvent =
+ createdTrigger === null ? undefined : parseTriggerListenEvent(eventData);
+ const filterResult =
+ createdTrigger === null
+ ? eventTypeOf(eventData) === slug
+ : matchesTriggerListenFilters(
+ { triggerId: createdTrigger.trigger_id },
+ parsedTriggerEvent!
+ );
if (debug) {
yield* emitStreamLine(
- `[debug] parsed.id=${parsed.id} triggerSlug=${parsed.triggerSlug} trigger_id=${createdTrigger.trigger_id} match=${filterResult}`,
+ createdTrigger === null
+ ? `[debug] event.type=${eventTypeOf(eventData) ?? '<missing>'} match=${filterResult}`
+ : `[debug] parsed.id=${parsedTriggerEvent!.id} triggerSlug=${parsedTriggerEvent!.triggerSlug} trigger_id=${createdTrigger.trigger_id} match=${filterResult}`,
ui
);
}
@@ -382,8 +461,9 @@ export const listenCmd = Command.make(
const eventJson = JSON.stringify(eventData, null, 2);
const streamEntry = JSON.stringify({
event_id: eventFileId,
- trigger_id: createdTrigger.trigger_id,
- trigger_slug: slug,
+ event_type: eventTypeOf(eventData),
+ trigger_id: createdTrigger?.trigger_id,
+ trigger_slug: createdTrigger ? slug : undefined,
file_path: eventFilePath,
received_at: new Date().toISOString(),
});
@@ -440,34 +520,44 @@ export const listenCmd = Command.make(
const stopReason = yield* Effect.raceFirst(listenEffect, Deferred.await(stopWhenDone));
if (stopReason === 'max-events') {
yield* ui.outro(
- `Stopped after receiving ${matchingEvents} events. Temporary trigger disabled.`
+ formatStopMessage({
+ matchingEvents,
+ timedOut: false,
+ temporaryTriggerDisabled: createdTrigger !== null,
+ })
);
return;
}
if (stopReason === 'timeout') {
yield* ui.outro(
- `Stopped after timeout with ${matchingEvents} matching event${matchingEvents === 1 ? '' : 's'}. Temporary trigger disabled.`
+ formatStopMessage({
+ matchingEvents,
+ timedOut: true,
+ temporaryTriggerDisabled: createdTrigger !== null,
+ })
);
}
}),
created =>
- Effect.tryPromise({
- try: () =>
- client.triggerInstances.manage.update(created.trigger_id, { status: 'disable' }),
- catch: error =>
- new Error(
- `Failed to disable temporary trigger "${created.trigger_id}": ${String(error)}`
- ),
- }).pipe(
- Effect.catchAll(error =>
- ui.log.warn(error instanceof Error ? error.message : String(error))
- )
- )
+ created === null
+ ? Effect.void
+ : Effect.tryPromise({
+ try: () =>
+ client.triggerInstances.manage.update(created.trigger_id, { status: 'disable' }),
+ catch: error =>
+ new Error(
+ `Failed to disable temporary trigger "${created.trigger_id}": ${String(error)}`
+ ),
+ }).pipe(
+ Effect.catchAll(error =>
+ ui.log.warn(error instanceof Error ? error.message : String(error))
+ )
+ )
);
})
).pipe(
Command.withDescription(
- 'Create a temporary subscription for consumer-project events and write each event to artifacts for easy background-agent consumption.'
+ 'Listen to consumer-project realtime events. Trigger slugs create a temporary trigger; top-level composio.* event types subscribe directly.'
)
);
diff --git a/ts/packages/cli/src/commands/root-help.ts b/ts/packages/cli/src/commands/root-help.ts
index 74523622e..0924a07b2 100644
--- a/ts/packages/cli/src/commands/root-help.ts
+++ b/ts/packages/cli/src/commands/root-help.ts
@@ -82,7 +82,7 @@ const CORE_COMMANDS: ReadonlyArray<TaggedValue<DetailedCommand>> = [
experimental('listen', {
name: 'listen',
description:
- 'Create a temporary subscription for consumer-project events and persist each payload into the session artifact folder.',
+ 'Listen to consumer-project realtime events and persist each payload into the session artifact folder.',
usage:
'listen <slug> [-p, --params text] [--max-events integer] [--timeout text] [--stream [text]]',
options: [
@@ -318,13 +318,19 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp> = {
usage:
'composio listen <slug> [-p, --params text] [--max-events integer] [--timeout text] [--stream [text]]',
description:
- 'Create a temporary subscription for consumer-project events so background agents can easily consume new emails, Slack messages, and other trigger payloads from artifacts.',
- args: [{ name: '<slug>', description: 'Trigger slug to create and listen to' }],
+ 'Listen to consumer-project realtime events. Trigger slugs create a temporary trigger; top-level composio.* event types subscribe directly.',
+ args: [
+ {
+ name: '<slug>',
+ description:
+ 'Trigger slug to create and listen to, or a project event type such as "composio.connected_account.expired"',
+ },
+ ],
options: [
{
name: '-p, --params <text>',
description:
- 'Trigger create params as JSON/JS object, @file, or - for stdin. Pass optional trigger config fields only.',
+ 'Trigger create params as JSON/JS object, @file, or - for stdin. Only valid for trigger slugs.',
},
{
name: '--max-events <integer>',
@@ -346,6 +352,7 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp> = {
'composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 5m',
"composio listen GMAIL_NEW_GMAIL_MESSAGE --timeout 1hr --stream '.data.threadId'",
'composio listen SLACK_RECEIVE_MESSAGE -p \'{ trigger_config: { channel: "C123" } }\'',
+ 'composio listen composio.connected_account.expired --max-events 1',
'composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream',
"composio listen GMAIL_NEW_GMAIL_MESSAGE -p @trigger.json --stream '.data.threadId'",
],
diff --git a/ts/packages/cli/test/__utils__/services/test-layer.ts b/ts/packages/cli/test/__utils__/services/test-layer.ts
index 2c6726a41..08eeab0ee 100644
--- a/ts/packages/cli/test/__utils__/services/test-layer.ts
+++ b/ts/packages/cli/test/__utils__/services/test-layer.ts
@@ -990,6 +990,24 @@ export const TestLayer = (input?: TestLiveInput) =>
return found;
},
},
+ triggerInstances: {
+ upsert: async (
+ triggerSlug: string,
+ params?: {
+ connected_account_id?: string;
+ trigger_config?: Record<string, unknown>;
+ }
+ ) => ({
+ trigger_id: `trg_${triggerSlug.toLowerCase()}_${params?.connected_account_id ?? 'new'}`,
+ }),
+ manage: {
+ update: async (triggerId: string, params: { status: 'enable' | 'disable' }) => ({
+ trigger_id: triggerId,
+ status: params.status,
+ }),
+ delete: async (triggerId: string) => ({ trigger_id: triggerId }),
+ },
+ },
toolkits: {
retrieve: async (slug: string) => {
const detailed = toolkitsData.detailedToolkits.find(
diff --git a/ts/packages/cli/test/src/analytics.events.test.ts b/ts/packages/cli/test/src/analytics.events.test.ts
index a959d20c1..5194ef7ad 100644
--- a/ts/packages/cli/test/src/analytics.events.test.ts
+++ b/ts/packages/cli/test/src/analytics.events.test.ts
@@ -121,6 +121,7 @@ describe('CLI analytics execute failure events', () => {
session: {
source: 'cli',
command_path: 'execute',
+ cli_version: expect.any(String),
},
request_id: 'req_123',
});
diff --git a/ts/packages/cli/test/src/commands/listen.cmd.test.ts b/ts/packages/cli/test/src/commands/listen.cmd.test.ts
new file mode 100644
index 000000000..268971f4d
--- /dev/null
+++ b/ts/packages/cli/test/src/commands/listen.cmd.test.ts
@@ -0,0 +1,127 @@
+import { describe, expect, layer } from '@effect/vitest';
+import { ConfigProvider, Effect } from 'effect';
+import { extendConfigProvider } from 'src/services/config';
+import { ComposioCliUserConfig } from 'src/services/cli-user-config';
+import { cli, MockConsole, TestLive } from 'test/__utils__';
+
+const testConfigProvider = ConfigProvider.fromMap(
+ new Map([['COMPOSIO_USER_API_KEY', 'test_api_key']])
+).pipe(extendConfigProvider);
+
+describe('CLI: composio listen', () => {
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ fixture: 'global-test-user-id',
+ realtimeData: {
+ events: [
+ {
+ id: 'evt_conn_expired_1',
+ type: 'composio.connected_account.expired',
+ timestamp: '2026-04-06T18:00:00.000Z',
+ metadata: {
+ project_id: 'consumer_project_id_test',
+ org_id: 'org_test',
+ },
+ data: {
+ id: 'con_expired_1',
+ },
+ },
+ ],
+ },
+ })
+ )(it => {
+ it.scoped(
+ '[Then] listens to top-level composio.* events without creating a temporary trigger',
+ () =>
+ Effect.gen(function* () {
+ const config = yield* ComposioCliUserConfig;
+ yield* config.update({
+ experimentalFeatures: {
+ ...config.raw.experimentalFeatures,
+ listen: true,
+ },
+ });
+ yield* cli(['listen', 'composio.connected_account.expired', '--max-events', '1']);
+
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('listening for events composio.connected_account.expired');
+ expect(output).toContain('/events/composio.connected_account.expired/');
+ expect(output).toContain('Stopped after receiving 1 event.');
+ expect(output).not.toContain('Temporary trigger disabled');
+ })
+ );
+ });
+
+ layer(
+ TestLive({
+ baseConfigProvider: testConfigProvider,
+ fixture: 'global-test-user-id',
+ connectedAccountsData: {
+ items: [
+ {
+ id: 'con_gmail_test',
+ status: 'ACTIVE',
+ status_reason: null,
+ is_disabled: false,
+ user_id: 'consumer-user-org_test',
+ toolkit: {
+ slug: 'gmail',
+ },
+ auth_config: {
+ id: 'auth_gmail_test',
+ auth_scheme: 'OAUTH2',
+ is_composio_managed: true,
+ is_disabled: false,
+ },
+ created_at: '2026-04-06T17:59:00.000Z',
+ updated_at: '2026-04-06T18:00:00.000Z',
+ test_request_endpoint: '',
+ },
+ ],
+ },
+ realtimeData: {
+ events: [
+ {
+ id: 'evt_trigger_1',
+ type: 'composio.trigger.message',
+ timestamp: '2026-04-06T18:00:00.000Z',
+ metadata: {
+ log_id: 'log_1',
+ trigger_slug: 'GMAIL_NEW_GMAIL_MESSAGE',
+ trigger_id: 'trg_gmail_new_gmail_message_con_gmail_test',
+ connected_account_id: 'con_gmail_test',
+ auth_config_id: 'auth_gmail_test',
+ user_id: 'consumer-user-org_test',
+ },
+ data: {
+ threadId: 'thread_123',
+ },
+ },
+ ],
+ },
+ })
+ )(it => {
+ it.scoped('[Then] keeps the temporary-trigger flow for trigger slugs', () =>
+ Effect.gen(function* () {
+ const config = yield* ComposioCliUserConfig;
+ yield* config.update({
+ experimentalFeatures: {
+ ...config.raw.experimentalFeatures,
+ listen: true,
+ },
+ });
+ yield* cli(['listen', 'GMAIL_NEW_GMAIL_MESSAGE', '--max-events', '1']);
+
+ const lines = yield* MockConsole.getLines({ stripAnsi: true });
+ const output = lines.join('\n');
+
+ expect(output).toContain('listening for events GMAIL_NEW_GMAIL_MESSAGE');
+ expect(output).toContain('/triggers/GMAIL_NEW_GMAIL_MESSAGE/');
+ expect(output).toContain('Stopped after receiving 1 event. Temporary trigger disabled.');
+ })
+ );
+ });
+});