@devries-cameron20 / composio-1 / commits / deee6066f
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

fix(cli): resolve project custom toolkits from tool slugs (#4587)

This PR: - closes #4499 - lists project-managed custom toolkits (`managed_by: 'project'`) via a new `getProjectToolkits(scope)` and unions them into the `toolkitFromToolSlug` miss path, so `CUSTOM_GRAIN_SEARCH_PERSONS` resolves to `custom_grain` instead of `custom` and `composio execute ... --account <selector>` picks the right account - scopes that lookup to the org/project the command resolved (`ToolkitProjectScope`), since consumer mode has no project context; memoized per scope in the cached repository and never written to `toolkits.json` - decodes toolkits that omit the optional `auth_schemes`, `composio_managed_auth_schemes`, and `no_auth` fields, as the API allows - `ToolkitSlugCatalog.remember` now merges slugs learned later in a run (serialized writes), so a custom toolkit found after the unscoped startup lookup is still remembered and later runs resolve it offline - `composio tools list <custom_slug>` with no results now suggests `composio search "<query>" --toolkits <slug>` (shared `isRemoteCustomToolkitSlug` predicate); native toolkits keep the existing hint ## Context Custom MCP toolkits are project-scoped and never in the baked slug catalog, so resolution fell back to the text before the first underscore. Plain `execute` worked because the Tool Router picked the account server-side; `--account` looked up accounts for toolkit `custom` and failed. Persistent per-toolkit approvals (the issue's third ask) already exist server-side as per-account `always_allow` overrides in Enhanced Controls; no CLI change. ## Verification - `pnpm typecheck`, `pnpm lint`, `pnpm --filter @composio/cli test` (133 files, 1437 passed), `pnpm validate:agent-skills`, `pnpm validate:skill-routing` - regression tests: resolver (project catalog, partial/total fetch failure, longest prefix, learned-slug reuse, merge after unscoped lookup), cached repository (per-scope memo, failure memo, no `toolkits.json` pollution), real-client request test (`managed_by=project` plus `x-org-id`/`x-project-id`), `execute --account` on a custom toolkit asserting every lookup uses the consumer project scope - **not verified live**: no API key was available to exercise `managed_by=project` against a real project with a custom MCP toolkit. Reviewers please run `composio execute CUSTOM_<X>_<TOOL> --account <id>` and `composio tools list custom_<x>` on such a project. - no changeset (`@composio/cli` is ignored by Changesets); no VHS recording, the only visible change is an empty-state hint ## Post-Deploy Monitoring & Validation - merge publishes a CLI beta; confirm with the #4499 reporter on that beta - watch CLI telemetry for `toolkitSlug: "custom"` on `CUSTOM_*` execute events; it should drop to near zero - failure signal: `No connected account matched ... for toolkit "custom"` reports persist on the beta; mitigate by reverting this PR (resolution falls back to prior behavior)

Alberto Schiabel committed Sep 23, 2026 at 19:41 UTC deee6066f3d278a581e8df55d893573b013ce4d1
23 files changed +1135 -97
ts/packages/cli/src/commands/listen.cmd.ts
+7 -2
@@ -5,7 +5,7 @@ import { NotFoundError, type Composio as RawComposioClient } from '@composio/cli
5 import { Data, Deferred, Effect, Result, Option, Predicate } from 'effect';
6 import { requireAuth } from 'src/effects/require-auth';
7 import { resolveOptionalTextInput } from 'src/effects/resolve-optional-text-input';
8 -import { ComposioClientSingleton } from 'src/services/composio-clients';
8 +import { ComposioClientSingleton, type ToolkitProjectScope } from 'src/services/composio-clients';
9 import {
10 formatResolveCommandProjectError,
11 resolveCommandProject,
@@ -186,9 +186,10 @@ const resolveConnectedAccountIdForTrigger = (params: {
186 slug: string;
187 consumerUserId: string;
188 account: Option.Option<string>;
189 + projectScope: ToolkitProjectScope;
190 }) =>
191 Effect.gen(function* () {
191 - const toolkitSlug = yield* toolkitFromToolSlug(params.slug);
192 + const toolkitSlug = yield* toolkitFromToolSlug(params.slug, params.projectScope);
193 if (!toolkitSlug) {
194 return yield* Effect.fail(
195 invalidOptionValue(
@@ -438,6 +439,10 @@ const resolveListenSetup = (params: {
439 slug: params.slug,
440 consumerUserId,
441 account: params.account,
442 + projectScope: {
443 + orgId: params.resolvedProject.orgId,
444 + projectId: params.resolvedProject.projectId,
445 + },
446 });
447
448 const createParams: TriggerCreateParams | undefined = listeningToProjectEvent
ts/packages/cli/src/commands/tools/commands/tools.execute.cmd.ts
+35 -8
@@ -24,7 +24,10 @@ import {
24 detectInBandWarning,
25 } from 'src/services/tools-executor';
26 import type { ToolExecuteParams, ToolExecuteResponse } from 'src/services/tools-executor';
27 -import { ComposioToolkitsRepository } from 'src/services/composio-clients';
27 +import {
28 + ComposioToolkitsRepository,
29 + type ToolkitProjectScope,
30 +} from 'src/services/composio-clients';
31 import { ComposioUserContext } from 'src/services/user-context';
32 import { ProjectContext } from 'src/services/project-context';
33 import { trackCliCodactFailureEffect, trackCliEventEffect } from 'src/analytics/dispatch';
@@ -451,9 +454,10 @@ const emitExecuteFailureTelemetry = (params: {
454 readonly stage: 'schema_fetch' | 'dry_run' | 'validation' | 'execution';
455 readonly logId?: string;
456 readonly mappedError?: ReturnType<typeof mapComposioError>;
457 + readonly projectScope?: ToolkitProjectScope;
458 }) =>
459 Effect.gen(function* () {
456 - const toolkitSlug = yield* toolkitFromToolSlug(params.toolSlug);
460 + const toolkitSlug = yield* toolkitFromToolSlug(params.toolSlug, params.projectScope);
461 const { invocationOrigin } = yield* cliInvocationContext;
462 const normalized = params.mappedError?.normalized ?? normalizeCliError(params.error);
463 const failureOrigin: 'fast_fail' | 'main_endpoint' =
@@ -705,10 +709,11 @@ const handleExecutionError = (
709 projectMode: 'consumer' | 'developer';
710 stage: 'schema_fetch' | 'dry_run' | 'validation' | 'execution';
711 logId?: string;
712 + projectScope?: ToolkitProjectScope;
713 }
714 ) =>
715 Effect.gen(function* () {
711 - const toolkit = yield* toolkitFromToolSlug(context.toolSlug);
716 + const toolkit = yield* toolkitFromToolSlug(context.toolSlug, context.projectScope);
717 const mapped = mapComposioError({ error, toolkit, toolSlug: context.toolSlug });
718 const normalized = mapped.normalized;
719 if (normalized instanceof ToolInputValidationError) {
@@ -720,6 +725,7 @@ const handleExecutionError = (
725 projectMode: context.projectMode,
726 stage: context.stage,
727 logId: context.logId,
728 + projectScope: context.projectScope,
729 });
730 yield* ui.log.error(`Input validation failed for ${context.toolSlug}`);
731 yield* ui.note(
@@ -742,6 +748,7 @@ const handleExecutionError = (
748 projectMode: context.projectMode,
749 stage: context.stage,
750 logId: context.logId,
751 + projectScope: context.projectScope,
752 mappedError: mapped,
753 });
754
@@ -973,6 +980,15 @@ type ResolvedExecuteContext = {
980 readonly executeOutputDir?: string;
981 };
982
983 +/**
984 + * The resolved project as toolkit resolution needs it: custom toolkits are
985 + * listed per project, and it has to be the project execute runs against.
986 + */
987 +const toolkitProjectScope = (resolvedProject: ToolkitProjectScope): ToolkitProjectScope => ({
988 + orgId: resolvedProject.orgId,
989 + projectId: resolvedProject.projectId,
990 +});
991 +
992 type ResolvedSchemaContext = {
993 readonly ui: TerminalUI;
994 readonly resolvedProject: {
@@ -1097,7 +1113,7 @@ const resolveExecuteContext = (params: RunToolsExecuteParams) =>
1113 });
1114 const toolkitSlug = isLocalToolSlug(params.slug)
1115 ? undefined
1100 - : yield* toolkitFromToolSlug(params.slug);
1116 + : yield* toolkitFromToolSlug(params.slug, toolkitProjectScope(resolvedProject));
1117 const selectedConnectedAccountId = yield* resolveConnectedAccountForToolkit({
1118 client,
1119 toolkitSlug,
@@ -1227,7 +1243,10 @@ const runConnectedToolkitFailFast = (params: {
1243 Effect.asVoid
1244 );
1245
1230 - const toolkit = yield* toolkitFromToolSlug(params.slug);
1246 + const toolkit = yield* toolkitFromToolSlug(
1247 + params.slug,
1248 + toolkitProjectScope(params.resolvedProject)
1249 + );
1250 if (!toolkit) return;
1251
1252 const cachedToolkits = yield* getFreshConsumerConnectedToolkitsFromCache({
@@ -1349,6 +1368,7 @@ const runExecuteWithSpinner = (params: {
1368 surface: params.surface,
1369 projectMode: params.projectMode,
1370 stage: 'dry_run',
1371 + projectScope: toolkitProjectScope(params.resolvedProject),
1372 })
1373 )
1374 )));
@@ -1366,6 +1386,7 @@ const runExecuteWithSpinner = (params: {
1386 surface: params.surface,
1387 projectMode: params.projectMode,
1388 stage: 'dry_run',
1389 + projectScope: toolkitProjectScope(params.resolvedProject),
1390 })
1391 )
1392 );
@@ -1419,6 +1440,7 @@ const runExecuteWithSpinner = (params: {
1440 surface: params.surface,
1441 projectMode: params.projectMode,
1442 stage: 'execution',
1443 + projectScope: toolkitProjectScope(params.resolvedProject),
1444 });
1445 yield* writeExecuteStdout(
1446 params.ui,
@@ -1474,6 +1496,7 @@ const runExecuteWithSpinner = (params: {
1496 projectMode: params.projectMode,
1497 stage: 'execution',
1498 logId: result.logId,
1499 + projectScope: toolkitProjectScope(params.resolvedProject),
1500 });
1501 yield* writeExecuteStdout(params.ui, JSON.stringify(result, ciRedactReplacer, 2));
1502 return yield* new ReportedToolExecutionError({
@@ -1559,6 +1582,7 @@ const runToolsExecute = (params: RunToolsExecuteParams) =>
1582 surface: params.surface,
1583 projectMode: params.projectMode,
1584 stage: 'schema_fetch',
1585 + projectScope: toolkitProjectScope(context.resolvedProject),
1586 })
1587 )
1588 );
@@ -1827,7 +1851,10 @@ const checkConnectedToolkitOrFail = (params: {
1851 Effect.asVoid
1852 );
1853
1830 - const toolkit = yield* toolkitFromToolSlug(params.slug);
1854 + const toolkit = yield* toolkitFromToolSlug(
1855 + params.slug,
1856 + toolkitProjectScope(params.resolvedProject)
1857 + );
1858 if (!toolkit) return;
1859
1860 const cachedToolkits = yield* getFreshConsumerConnectedToolkitsFromCache({
@@ -1889,7 +1916,7 @@ const runParallelSchemaFetchFromParsed = (params: ParsedParallelExecuteArgs) =>
1916 >;
1917 }).pipe(
1918 Effect.catch(error =>
1892 - toolkitFromToolSlug(spec.slug).pipe(
1919 + toolkitFromToolSlug(spec.slug, toolkitProjectScope(context.resolvedProject)).pipe(
1920 Effect.map(toolkit => {
1921 const mapped = mapComposioError({ error, toolkit, toolSlug: spec.slug });
1922 return {
@@ -2041,7 +2068,7 @@ const runParallelToolsExecuteFromParsed = (params: ParsedParallelExecuteArgs) =>
2068 };
2069 }).pipe(
2070 Effect.catch(error =>
2044 - toolkitFromToolSlug(spec.slug).pipe(
2071 + toolkitFromToolSlug(spec.slug, toolkitProjectScope(context.resolvedProject)).pipe(
2072 Effect.map(toolkit => {
2073 const mapped = mapComposioError({ error, toolkit, toolSlug: spec.slug });
2074 return {
ts/packages/cli/src/commands/tools/commands/tools.list.cmd.ts
+5 -1
@@ -3,6 +3,8 @@ import { Effect, Option } from 'effect';
3 import { ComposioToolkitsRepository } from 'src/services/composio-clients';
4 import { TerminalUI } from 'src/services/terminal-ui';
5 import { requireAuth } from 'src/effects/require-auth';
6 +import { commandHintStep } from 'src/services/command-hints';
7 +import { isRemoteCustomToolkitSlug } from 'src/utils/remote-custom-toolkit';
8 import { clampLimit } from 'src/ui/clamp-limit';
9 import { formatToolsTable, formatToolsJson } from '../format';
10
@@ -59,7 +61,9 @@ export const toolsCmd$List = Command.make(
61
62 if (result.items.length === 0) {
63 yield* ui.log.warn(
62 - `No tools found in toolkit "${toolkit}". Verify the toolkit slug with:\n> composio dev toolkits list`
64 + isRemoteCustomToolkitSlug(toolkit)
65 + ? `No tools found in toolkit "${toolkit}". Custom toolkit tools are served by the Tool Router. ${commandHintStep('Discover them with', 'root.search', { toolkits: toolkit })}`
66 + : `No tools found in toolkit "${toolkit}". Verify the toolkit slug with:\n> composio dev toolkits list`
67 );
68 return;
69 }
ts/packages/cli/src/commands/tools/commands/tools.search.cmd.ts
+1 -2
@@ -17,6 +17,7 @@ import {
17 formatResolveCommandProjectError,
18 } from 'src/services/command-project';
19 import { commandHintExample, commandHintStep } from 'src/services/command-hints';
20 +import { isRemoteCustomToolSlug } from 'src/utils/remote-custom-toolkit';
21 import {
22 primeConsumerConnectedToolkitsCacheInBackground,
23 writeConsumerConnectedToolkitsCache,
@@ -96,8 +97,6 @@ const stripSearchResultMetadata = <
97
98 const TOOL_SCHEMA_PATH_FORMAT = '~/.composio/tool_definitions/<TOOL_SLUG>.json';
99
99 -const isRemoteCustomToolSlug = (slug: string): boolean => slug.toUpperCase().startsWith('CUSTOM_');
100 -
100 const toHomeRelativePath = (cacheDir: string, absolutePath: string) =>
101 absolutePath.startsWith(cacheDir) ? absolutePath.replace(cacheDir, '~/.composio') : absolutePath;
102
ts/packages/cli/src/effects/toolkit-from-tool-slug.ts
+36 -8
@@ -1,6 +1,10 @@
1 -import { Effect } from 'effect';
2 -import { ComposioToolkitsRepository } from 'src/services/composio-clients';
1 +import { Array as Arr, Effect, Option } from 'effect';
2 +import {
3 + ComposioToolkitsRepository,
4 + type ToolkitProjectScope,
5 +} from 'src/services/composio-clients';
6 import { ToolkitSlugCatalog } from 'src/services/toolkit-slug-catalog';
7 +import { isRemoteCustomToolkitSlug } from 'src/utils/remote-custom-toolkit';
8 import { isMetaToolSlug } from 'src/utils/meta-tool-slugs';
9 import {
10 guessToolkitFromToolSlug,
@@ -18,13 +22,20 @@ import {
22 * this machine has learned since, both local and memoized per run, so the
23 * common case costs no network at all.
24 *
21 - * Only a slug that matches nothing known falls through to the catalog, which
22 - * is what a toolkit released after this binary looks like. Everything else
25 + * Native matches resolve locally. Custom matches are checked against the
26 + * active project; unknown slugs also fall through to the catalog, which
27 + * is what a toolkit released after this binary looks like — or a custom
28 + * toolkit registered in the current project. Everything else
29 * degrades rather than fails: an unreachable catalog still yields the
30 * first-underscore guess.
31 + *
32 + * Pass the org/project the command resolved as `scope`: custom toolkits are
33 + * listed per project, and without it the list follows the project context,
34 + * which in consumer mode is no project at all.
35 */
36 export const toolkitFromToolSlug = (
27 - toolSlug: string
37 + toolSlug: string,
38 + scope?: ToolkitProjectScope
39 ): Effect.Effect<string | undefined, never, ComposioToolkitsRepository | ToolkitSlugCatalog> =>
40 Effect.gen(function* () {
41 // Meta tools belong to the session rather than to a toolkit, and their
@@ -39,13 +50,30 @@ export const toolkitFromToolSlug = (
50 const local = yield* catalog.local;
51
52 const match = local.longestPrefix(toolSlug);
42 - if (match !== undefined) {
53 + if (match !== undefined && !isRemoteCustomToolkitSlug(match)) {
54 return toolkitFromMatchedPrefix(match);
55 }
56
57 + // Project-scoped custom toolkits are never in the Composio-managed
58 + // catalog, so a miss asks for both. Either one alone is still worth
59 + // matching against; only when neither answers does the guess win.
60 const repository = yield* ComposioToolkitsRepository;
47 - const toolkits = yield* repository.getToolkits();
48 - const allSlugs = [...local.slugs, ...toolkits.map(toolkit => toolkit.slug)];
61 + const catalogs = yield* Effect.all(
62 + [repository.getToolkits(), repository.getProjectToolkits(scope)].map(Effect.option),
63 + { concurrency: 'unbounded' }
64 + );
65 + const fetched = Arr.getSomes(catalogs);
66 + if (!Arr.isReadonlyArrayNonEmpty(fetched)) {
67 + return matchToolkitFromToolSlug(toolSlug, local.slugs);
68 + }
69 +
70 + // A successful project lookup is authoritative: machine-wide custom slugs
71 + // may belong to another project, including longer or shorter prefixes.
72 + // Retain learned slugs only as a best-effort fallback during an outage.
73 + const localSlugs = Option.isSome(catalogs[1])
74 + ? local.slugs.filter(slug => !isRemoteCustomToolkitSlug(slug))
75 + : local.slugs;
76 + const allSlugs = [...localSlugs, ...fetched.flat().map(toolkit => toolkit.slug)];
77
78 yield* catalog.remember(allSlugs);
79
ts/packages/cli/src/models/toolkits.ts
+8 -3
@@ -28,8 +28,13 @@ export const ToolkitSlug = Schema.Trim.check(
28 export const Toolkit = Schema.Struct({
29 name: Schema.String, // "Gmail"
30 slug: ToolkitSlug, // "gmail"
31 - auth_schemes: Schema.Array(Schema.String), // [ "OAUTH2", "BEARER_TOKEN" ]
32 - composio_managed_auth_schemes: Schema.Array(Schema.String), // [ "OAUTH2" ]
31 + // The API marks the auth fields optional; project custom toolkits may omit them.
32 + auth_schemes: Schema.Array(Schema.String).pipe(
33 + Schema.withDecodingDefaultType(Effect.succeed([]))
34 + ), // [ "OAUTH2", "BEARER_TOKEN" ]
35 + composio_managed_auth_schemes: Schema.Array(Schema.String).pipe(
36 + Schema.withDecodingDefaultType(Effect.succeed([]))
37 + ), // [ "OAUTH2" ]
38 is_local_toolkit: Schema.Boolean,
39 meta: Schema.Struct({
40 description: Schema.String,
@@ -42,7 +47,7 @@ export const Toolkit = Schema.Struct({
47 tools_count: Schema.Int.pipe(Schema.withDecodingDefaultType(Effect.succeed(0))),
48 triggers_count: Schema.Int.pipe(Schema.withDecodingDefaultType(Effect.succeed(0))),
49 }),
45 - no_auth: Schema.Boolean,
50 + no_auth: Schema.Boolean.pipe(Schema.withDecodingDefaultType(Effect.succeed(false))),
51 }).annotate({ identifier: 'Toolkit' });
52 export type Toolkit = Schema.Schema.Type<typeof Toolkit>;
53
ts/packages/cli/src/services/command-hints.ts
+5 -1
@@ -35,7 +35,11 @@ type CommandHintNode = {
35
36 export const COMMAND_HINTS: Record<CommandHintId, CommandHintNode> = {
37 'root.search': {
38 - example: params => `composio search "${getParam(params, 'query', '<query>')}"`,
38 + example: params => {
39 + const toolkits = params?.toolkits?.trim();
40 + const search = `composio search "${getParam(params, 'query', '<query>')}"`;
41 + return toolkits ? `${search} --toolkits ${toolkits}` : search;
42 + },
43 links: ['root.execute', 'root.link', 'root.tools.list'],
44 },
45 'root.tools.list': {
ts/packages/cli/src/services/composio-clients-cached.ts
+32 -1
@@ -5,7 +5,11 @@ import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
5 import { setupCacheDir } from 'src/effects/setup-cache-dir';
6 import { FORCE_CONFIG } from 'src/effects/force-config';
7 import { writeFileAtomic } from 'src/effects/write-file-atomic';
8 -import { ComposioToolkitsRepository, InvalidToolkitsError } from './composio-clients';
8 +import {
9 + ComposioToolkitsRepository,
10 + InvalidToolkitsError,
11 + type ToolkitProjectScope,
12 +} from './composio-clients';
13 import type { ToolkitVersionSpec } from 'src/effects/toolkit-version-overrides';
14 import { NodeOs } from './node-os';
15 import { toolkitsFromJSON, toolkitsToJSON, type Toolkits } from 'src/models/toolkits';
@@ -180,12 +184,39 @@ export const ComposioToolkitsRepositoryCached = Layer.effect(
184 )
185 );
186
187 + // Project toolkits are never written to `toolkits.json`: that file holds
188 + // the Composio-managed catalog, and its readers assume nothing else is in
189 + // it. They are still memoized, because every toolkit resolution that
190 + // misses locally asks for them. Under `FORCE_USE_CACHE` replay the fetch
191 + // still reaches the API, and a failure only costs toolkit resolution its
192 + // fallback guess.
193 + //
194 + // The list depends on the project it is asked for, so each scope gets its
195 + // own memo (the unscoped call is one more key), with the same
196 + // failure-is-final semantics as `cachedGetToolkits`. The memo is created
197 + // synchronously so that concurrent first callers share it.
198 + const projectToolkitsByScope = new Map<
199 + string,
200 + ReturnType<typeof underlyingRepository.getProjectToolkits>
201 + >();
202 + const cachedGetProjectToolkits = (scope?: ToolkitProjectScope) =>
203 + Effect.suspend(() => {
204 + const key = scope ? JSON.stringify([scope.orgId, scope.projectId]) : '';
205 + const memo =
206 + projectToolkitsByScope.get(key) ??
207 + Effect.runSync(Effect.cached(underlyingRepository.getProjectToolkits(scope)));
208 + projectToolkitsByScope.set(key, memo);
209 + return memo;
210 + });
211 +
212 // Create the cached implementation that wraps the original implementation
213 return ComposioToolkitsRepository.of({
214 // Memoized per layer instance; `getToolkitsBySlugs` stays unmemoized
215 // because its result depends on the requested slugs.
216 getToolkits: () => cachedGetToolkits,
217
218 + getProjectToolkits: cachedGetProjectToolkits,
219 +
220 getToolkitsBySlugs: slugs => {
221 const cacheFilter = (data: Toolkits) => {
222 const slugSet = new Set(slugs.map(s => s.toUpperCase()));
ts/packages/cli/src/services/composio-clients.ts
+41 -5
@@ -1623,6 +1623,27 @@ const makeComposioClientSingleton = Effect.gen(function* () {
1623 };
1624 });
1625
1626 +/**
1627 + * The org/project a project-scoped request is made for, as a command resolved it.
1628 + */
1629 +export interface ToolkitProjectScope {
1630 + readonly orgId: string;
1631 + readonly projectId: string;
1632 +}
1633 +
1634 +/**
1635 + * A view of `clientSingleton` whose `get()` builds the client for `scope`,
1636 + * so the shared call helpers can make a request for a project other than the
1637 + * one the project context resolves.
1638 + */
1639 +const scopedClientSingleton = (
1640 + clientSingleton: ComposioClientSingletonShape,
1641 + scope: ToolkitProjectScope
1642 +): ComposioClientSingletonShape => ({
1643 + ...clientSingleton,
1644 + get: () => clientSingleton.getFor({ orgId: scope.orgId, projectId: scope.projectId }),
1645 +});
1646 +
1647 export class ComposioClientSingleton extends Context.Service<
1648 ComposioClientSingleton,
1649 ComposioClientSingletonShape
@@ -1914,12 +1935,15 @@ const makeComposioClientLive = Effect.gen(function* () {
1935 /**
1936 * Retrieves a comprehensive list of toolkits that are available to the authenticated project.
1937 * Automatically handles pagination to fetch all items.
1938 + * @param managedBy - Which toolkits to list; the API defaults to Composio-managed ones
1939 + * @param scope - The org/project to list for, instead of the one the project context resolves
1940 */
1918 - list: () =>
1941 + list: (managedBy?: 'composio' | 'project' | 'all', scope?: ToolkitProjectScope) =>
1942 withMetrics(
1943 callClientWithPagination(
1921 - clientSingleton,
1922 - (client, cursor, limit) => client.toolkits.list({ cursor, limit }),
1944 + scope ? scopedClientSingleton(clientSingleton, scope) : clientSingleton,
1945 + (client, cursor, limit) =>
1946 + client.toolkits.list({ cursor, limit, managed_by: managedBy }),
1947 ToolkitsResponse
1948 )
1949 ),
@@ -2097,12 +2121,23 @@ export class ComposioClientLive extends Context.Service<
2121 const makeComposioToolkitsRepository = Effect.gen(function* () {
2122 const client = yield* ComposioClientLive;
2123
2100 - const getToolkits = () =>
2101 - client.toolkits.list().pipe(
2124 + const listToolkits = (managedBy?: 'project', scope?: ToolkitProjectScope) =>
2125 + client.toolkits.list(managedBy, scope).pipe(
2126 Effect.map(response => response.items),
2127 Effect.map(items => sortBySlug(items) as ReadonlyArray<Toolkit>)
2128 );
2129
2130 + const getToolkits = () => listToolkits();
2131 +
2132 + /**
2133 + * Fetches the custom toolkits registered in the current project. They are
2134 + * project-scoped, so they are absent from the build-time catalog and from
2135 + * {@link getToolkits}, whose callers expect Composio-managed toolkits only.
2136 + * @param scope - The org/project the command resolved; without it, the
2137 + * project context decides, which is no project at all in consumer mode
2138 + */
2139 + const getProjectToolkits = (scope?: ToolkitProjectScope) => listToolkits('project', scope);
2140 +
2141 /**
2142 * Fetches specific toolkits by their slugs.
2143 * Makes parallel API calls to retrieve each toolkit.
@@ -2133,6 +2168,7 @@ const makeComposioToolkitsRepository = Effect.gen(function* () {
2168
2169 return {
2170 getToolkits,
2171 + getProjectToolkits,
2172 getToolkitsBySlugs,
2173 getMetrics: () => client.getMetrics(),
2174 getToolsAsEnums: () => client.tools.retrieveEnum(),
ts/packages/cli/src/services/known-toolkit-slugs.ts
+10 -3
@@ -21,6 +21,11 @@ import { NodeOs } from './node-os';
21 * this file can only cost a fetch, never an answer: an unknown slug falls
22 * through to the catalog, and the backend never removes a toolkit, so a slug
23 * recorded here never stops being real.
24 + *
25 + * Custom toolkits are the exception: they belong to a project, can be deleted,
26 + * and this file is shared by every project on the machine. The resolver checks
27 + * custom matches against the active project's catalog before accepting them.
28 + * Learned custom slugs are only a best-effort fallback when that lookup fails.
29 */
30
31 export const KNOWN_TOOLKIT_SLUGS_FILE = 'known-toolkit-slugs.json';
@@ -72,17 +77,19 @@ export const readKnownToolkitSlugs: Effect.Effect<Option.Option<KnownToolkitSlug
77 );
78
79 /**
75 - * Records `slugs`, sorted and deduped, stamped with the current time.
80 + * Records `slugs`, sorted and deduped, with the last full catalog refresh time.
81 *
82 * Never fails: this is an optimization, and a machine that cannot write to its
83 * own cache directory should still be able to run tools. Concurrent CLI
84 * processes are safe by construction — the write is atomic, and since slugs
85 * are only ever added, whichever writer lands last leaves a usable file.
86 */
82 -export const writeKnownToolkitSlugs = (slugs: ReadonlyArray<string>): Effect.Effect<void> =>
87 +export const writeKnownToolkitSlugs = (
88 + slugs: ReadonlyArray<string>,
89 + refreshedAt: DateTime.Utc
90 +): Effect.Effect<void> =>
91 Effect.gen(function* () {
92 const filePath = yield* knownToolkitSlugsPath;
85 - const refreshedAt = yield* DateTime.now;
93
94 const content = yield* Schema.encodeEffect(KnownToolkitSlugsJSON)({
95 slugs: [...new Set(slugs.map(slug => slug.toLowerCase()))].sort(),
ts/packages/cli/src/services/toolkit-slug-catalog.ts
+65 -28
@@ -1,4 +1,4 @@
1 -import { DateTime, Duration, Effect, Option, Ref, Context, Layer } from 'effect';
1 +import { DateTime, Duration, Effect, Option, Ref, Semaphore, Context, Layer } from 'effect';
2 import { BAKED_TOOLKIT_SLUGS } from 'src/generated/toolkit-slugs';
3 import { ComposioToolkitsRepository } from 'src/services/composio-clients';
4 import {
@@ -34,19 +34,37 @@ const learnedSlugs = (learned: Option.Option<KnownToolkitSlugs>): ReadonlyArray<
34 /**
35 * Re-reads the catalog and records it, in the background. Failures are
36 * swallowed: a refresh that does not happen costs a fetch later, nothing more.
37 + * The project's custom toolkits are optional to it — without them, a custom
38 + * toolkit still uses its learned slug if the scoped fetch also fails. Refresh
39 + * and foreground discoveries merge through the same serialized writer.
40 */
38 -const refreshKnownToolkitSlugs = Effect.gen(function* () {
39 - const repository = yield* ComposioToolkitsRepository;
40 - const toolkits = yield* repository.getToolkits();
41 - yield* writeKnownToolkitSlugs([...BAKED_TOOLKIT_SLUGS, ...toolkits.map(t => t.slug)]);
42 -}).pipe(Effect.timeout(REFRESH_TIMEOUT), Effect.ignore);
41 +const refreshKnownToolkitSlugs = (
42 + remember: (slugs: ReadonlyArray<string>) => Effect.Effect<void>
43 +) =>
44 + Effect.gen(function* () {
45 + const repository = yield* ComposioToolkitsRepository;
46 + const [toolkits, projectToolkits] = yield* Effect.all(
47 + [
48 + repository.getToolkits(),
49 + repository.getProjectToolkits().pipe(Effect.orElseSucceed(() => [])),
50 + ],
51 + { concurrency: 'unbounded' }
52 + );
53 + yield* remember([
54 + ...BAKED_TOOLKIT_SLUGS,
55 + ...[...toolkits, ...projectToolkits].map(t => t.slug),
56 + ]);
57 + }).pipe(Effect.timeout(REFRESH_TIMEOUT), Effect.ignore);
58
59 /**
60 * Starts a refresh when the learned slugs are missing or older than
61 * {@link REFRESH_AFTER}. A `refreshedAt` in the future (a clock that jumped)
62 * counts as fresh — the point is to bound staleness, not to police clocks.
63 */
49 -const refreshInBackgroundIfStale = (learned: Option.Option<KnownToolkitSlugs>) =>
64 +const refreshInBackgroundIfStale = (
65 + learned: Option.Option<KnownToolkitSlugs>,
66 + remember: (slugs: ReadonlyArray<string>) => Effect.Effect<void>
67 +) =>
68 Effect.gen(function* () {
69 const now = yield* DateTime.now;
70 const isFresh = Option.match(learned, {
@@ -57,7 +75,7 @@ const refreshInBackgroundIfStale = (learned: Option.Option<KnownToolkitSlugs>) =
75
76 if (isFresh) return;
77
60 - yield* Effect.forkDetach(refreshKnownToolkitSlugs);
78 + yield* Effect.forkDetach(refreshKnownToolkitSlugs(remember));
79 });
80
81 /**
@@ -74,15 +92,6 @@ export interface LocalToolkitSlugs {
92 readonly longestPrefix: (toolSlug: string) => string | undefined;
93 }
94
77 -const loadLocalToolkitSlugs = Effect.gen(function* () {
78 - const learned = yield* readKnownToolkitSlugs;
79 - const slugs = [...BAKED_TOOLKIT_SLUGS, ...learnedSlugs(learned)];
80 -
81 - yield* refreshInBackgroundIfStale(learned);
82 -
83 - return { slugs, longestPrefix: makeLongestPrefixMatcher(slugs) } satisfies LocalToolkitSlugs;
84 -});
85 -
95 /**
96 * Owns the local half of toolkit resolution, resolved once per process.
97 *
@@ -98,23 +107,51 @@ const loadLocalToolkitSlugs = Effect.gen(function* () {
107 * unmemoized read forked — and rewrote the file — once per resolution.
108 */
109 const makeToolkitSlugCatalog = Effect.gen(function* () {
101 - const local = yield* Effect.cached(loadLocalToolkitSlugs);
102 - const hasRecorded = yield* Ref.make(false);
110 + const recorded = yield* Ref.make<ReadonlySet<string>>(new Set());
111 + const writes = yield* Semaphore.make(1);
112 + const refreshedAt = yield* Ref.make(DateTime.makeUnsafe(0));
113
114 /**
105 - * Records slugs learned from a catalog fetch, in the background, at most
106 - * once per run. Every miss in a run merges the same memoized fetch into
107 - * the same local list, so later calls would fork a daemon fiber only to
108 - * rewrite an identical file — and each pending fiber holds the finished
109 - * command open a little longer.
115 + * Records slugs learned from a catalog fetch, in the background, only when
116 + * they add something. Most misses in a run merge the same memoized fetch,
117 + * and rewriting an identical file would only hold the finished command open
118 + * longer; but a later miss can see a catalog an earlier one did not (the
119 + * command's own project, after an unscoped startup lookup), and those slugs
120 + * must not be dropped. Writes are serialized and each writes everything
121 + * recorded so far, so a slow earlier write never lands over a later one.
122 */
111 - const remember = (slugs: ReadonlyArray<string>): Effect.Effect<void> =>
123 + const remember = (slugs: ReadonlyArray<string>, refresh = false): Effect.Effect<void> =>
124 Effect.gen(function* () {
113 - const alreadyRecorded = yield* Ref.getAndSet(hasRecorded, true);
114 - if (alreadyRecorded) return;
115 - yield* Effect.forkDetach(writeKnownToolkitSlugs(slugs));
125 + const learnedSomething = yield* Ref.modify(recorded, current => {
126 + const next = new Set([...current, ...slugs.map(slug => slug.toLowerCase())]);
127 + return [next.size > current.size, next] as const;
128 + });
129 + if (!learnedSomething && !refresh) return;
130 + // Partial foreground discoveries do not prove the native catalog is
131 + // current. Only a successful background refresh advances freshness.
132 + if (refresh) yield* Ref.set(refreshedAt, yield* DateTime.now);
133 + yield* Effect.forkDetach(
134 + writes.withPermits(1)(
135 + Effect.gen(function* () {
136 + const slugs = yield* Ref.get(recorded);
137 + const lastRefresh = yield* Ref.get(refreshedAt);
138 + yield* writeKnownToolkitSlugs([...slugs], lastRefresh);
139 + })
140 + )
141 + );
142 });
143
144 + const local = yield* Effect.cached(
145 + Effect.gen(function* () {
146 + const learned = yield* readKnownToolkitSlugs;
147 + const slugs = [...BAKED_TOOLKIT_SLUGS, ...learnedSlugs(learned)];
148 + if (Option.isSome(learned)) yield* Ref.set(refreshedAt, learned.value.refreshedAt);
149 + yield* Ref.update(recorded, current => new Set([...current, ...slugs]));
150 + yield* refreshInBackgroundIfStale(learned, slugs => remember(slugs, true));
151 + return { slugs, longestPrefix: makeLongestPrefixMatcher(slugs) } satisfies LocalToolkitSlugs;
152 + })
153 + );
154 +
155 return { local, remember };
156 });
157
ts/packages/cli/src/services/tools-executor.ts
+14 -3
@@ -7,7 +7,7 @@ import type {
7 SessionExecuteResponse,
8 SessionExecuteMetaResponse,
9 } from '@composio/client/resources/tool-router';
10 -import { ComposioClientSingleton } from 'src/services/composio-clients';
10 +import { ComposioClientSingleton, type ToolkitProjectScope } from 'src/services/composio-clients';
11 import { createToolRouterSessionContext } from 'src/effects/create-tool-router-session';
12 import { gateToolExecution, type PermissionGateResult } from 'src/services/tool-permissions';
13 import {
@@ -52,6 +52,17 @@ export interface ToolExecuteParams {
52 };
53 }
54
55 +/**
56 + * The project custom toolkits are listed for: the command's resolved one when
57 + * it handed in both ids, otherwise whatever the project context resolves.
58 + */
59 +const toolkitProjectScope = ({
60 + projectScope,
61 +}: ToolExecuteParams): ToolkitProjectScope | undefined =>
62 + projectScope?.orgId && projectScope.projectId
63 + ? { orgId: projectScope.orgId, projectId: projectScope.projectId }
64 + : undefined;
65 +
66 /**
67 * Normalized response that matches the shape consumers expect.
68 */
@@ -197,7 +208,7 @@ export const ToolsExecutorLive = Layer.effect(
208 connectedAccounts: params.connectedAccounts,
209 cacheScope: params.cacheScope,
210 });
200 - const toolkitSlug = yield* toolkitFromToolSlug(slug);
211 + const toolkitSlug = yield* toolkitFromToolSlug(slug, toolkitProjectScope(params));
212 const permissionGateResult = yield* gateToolExecution({
213 toolSlug: slug,
214 connectedAccountId: toolkitSlug ? connectedAccounts?.[toolkitSlug] : undefined,
@@ -263,7 +274,7 @@ export const ToolsExecutorLive = Layer.effect(
274 return normalizeResponse(raw, permissionGateResult);
275 }).pipe(
276 Effect.catch(error =>
266 - toolkitFromToolSlug(slug).pipe(
277 + toolkitFromToolSlug(slug, toolkitProjectScope(params)).pipe(
278 Effect.flatMap(toolkitSlug => {
279 const mapped = mapComposioError({ error, toolkit: toolkitSlug, toolSlug: slug });
280 return Effect.fail(
ts/packages/cli/src/utils/remote-custom-toolkit.ts new
+21
@@ -0,0 +1,21 @@
1 +const REMOTE_CUSTOM_PREFIX = 'CUSTOM_';
2 +
3 +/**
4 + * Whether a toolkit slug names a project-scoped custom MCP toolkit (e.g. `custom_grain`).
5 + *
6 + * These toolkits are served by the Tool Router session, not the REST tools index.
7 + * Native toolkits whose slug merely starts with "custom" (`customerio`, `customgpt`, ...)
8 + * do not match, because they lack the `custom_` separator.
9 + */
10 +export const isRemoteCustomToolkitSlug = (slug: string): boolean => {
11 + const normalized = slug.toUpperCase();
12 + return (
13 + normalized.startsWith(REMOTE_CUSTOM_PREFIX) && normalized.length > REMOTE_CUSTOM_PREFIX.length
14 + );
15 +};
16 +
17 +/**
18 + * Whether a tool slug belongs to a remote custom toolkit (e.g. `CUSTOM_GRAIN_SEARCH_PERSONS`).
19 + * Tool slugs carry their toolkit slug as a prefix, so the toolkit predicate applies directly.
20 + */
21 +export const isRemoteCustomToolSlug = (slug: string): boolean => isRemoteCustomToolkitSlug(slug);
ts/packages/cli/test/__utils__/services/test-layer.ts
+26
@@ -35,6 +35,7 @@ import {
35 InvalidToolkitsError,
36 InvalidToolkitVersionsError,
37 type InvalidVersionDetail,
38 + type ToolkitProjectScope,
39 } from 'src/services/composio-clients';
40 import type { ToolkitVersionOverrides } from 'src/effects/toolkit-version-overrides';
41 import { JsPackageManagerDetector } from 'src/services/js-package-manager-detector';
@@ -111,6 +112,21 @@ export interface TestLiveInput {
112 */
113 toolkitsData?: {
114 toolkits?: Toolkits;
115 + /**
116 + * Custom toolkits registered in the test project. Kept apart from
117 + * `toolkits`, the Composio-managed catalog, as the API keeps them apart.
118 + */
119 + projectToolkits?: Toolkits;
120 + /**
121 + * The project `projectToolkits` belong to. When set, a project-toolkit
122 + * lookup for any other scope, or for none, finds nothing, as the API
123 + * would answer for another project.
124 + */
125 + projectToolkitsScope?: ToolkitProjectScope;
126 + /**
127 + * Called with the scope of every project-toolkit lookup.
128 + */
129 + onGetProjectToolkits?: (scope: ToolkitProjectScope | undefined) => void;
130 detailedToolkits?: ToolkitDetailed[];
131 tools?: Tools;
132 triggerTypesAsEnums?: TriggerTypesAsEnums;
@@ -305,6 +321,7 @@ export const TestLayer = (input?: TestLiveInput) =>
321 Effect.gen(function* () {
322 const defaultAppClientData = {
323 toolkits: [] as Toolkits,
324 + projectToolkits: [] as Toolkits,
325 detailedToolkits: [] as ToolkitDetailed[],
326 tools: [] as Tools,
327 triggerTypesAsEnums: [] as TriggerTypesAsEnums,
@@ -359,6 +376,15 @@ export const TestLayer = (input?: TestLiveInput) =>
376 ComposioToolkitsRepository,
377 ComposioToolkitsRepository.of({
378 getToolkits: () => Effect.succeed(toolkitsData.toolkits),
379 + getProjectToolkits: scope =>
380 + Effect.sync(() => {
381 + toolkitsData.onGetProjectToolkits?.(scope);
382 + const owner = toolkitsData.projectToolkitsScope;
383 + const inScope =
384 + owner === undefined ||
385 + (scope?.orgId === owner.orgId && scope.projectId === owner.projectId);
386 + return inScope ? toolkitsData.projectToolkits : [];
387 + }),
388 getToolkitsBySlugs: (slugs: ReadonlyArray<string>) => {
389 const normalizedSlugs = new Set(slugs.map(s => String.toLowerCase(s)));
390 const found = toolkitsData.toolkits.filter(t =>
ts/packages/cli/test/__utils__/services/toolkits-repository-stub.ts
+18 -3
@@ -2,6 +2,7 @@ import { Effect, Layer } from 'effect';
2 import {
3 ComposioToolkitsRepository,
4 type ComposioToolkitsRepositoryShape,
5 + type ToolkitProjectScope,
6 } from 'src/services/composio-clients';
7 import type { Toolkits } from 'src/models/toolkits';
8
@@ -49,14 +50,23 @@ const unusedRepositoryMethods = {
50 deleteTrigger: notUsed('deleteTrigger'),
51 } as const;
52
53 +export type GetProjectToolkitsError = Effect.Error<
54 + ReturnType<ComposioToolkitsRepositoryShape['getProjectToolkits']>
55 +>;
56 +
57 /**
58 * A `ComposioToolkitsRepository` layer that counts catalog fetches, so a test
54 - * can assert not just what was resolved but what it cost.
59 + * can assert not just what was resolved but what it cost. The native and
60 + * project-managed catalogs are counted separately.
61 */
62 export const countingToolkitsRepository = (
57 - getToolkits: () => Effect.Effect<Toolkits, GetToolkitsError>
63 + getToolkits: () => Effect.Effect<Toolkits, GetToolkitsError>,
64 + getProjectToolkits: (
65 + scope?: ToolkitProjectScope
66 + ) => Effect.Effect<Toolkits, GetProjectToolkitsError> = () => Effect.succeed([])
67 ) => {
68 let calls = 0;
69 + let projectCalls = 0;
70
71 const layer = Layer.succeed(
72 ComposioToolkitsRepository,
@@ -67,8 +77,13 @@ export const countingToolkitsRepository = (
77 calls += 1;
78 return getToolkits();
79 }),
80 + getProjectToolkits: scope =>
81 + Effect.suspend(() => {
82 + projectCalls += 1;
83 + return getProjectToolkits(scope);
84 + }),
85 })
86 );
87
73 - return { layer, calls: () => calls };
88 + return { layer, calls: () => calls, projectCalls: () => projectCalls };
89 };
ts/packages/cli/test/src/commands/tools/tools.execute.cmd.test.ts
+170
@@ -40,6 +40,26 @@ const testConfigProvider = ConfigProvider.fromEnv({
40 env: { COMPOSIO_USER_API_KEY: 'test_api_key' },
41 }).pipe(extendConfigProvider);
42
43 +// `testConfigProvider` pins its env, so it bypasses the per-test
44 +// `COMPOSIO_CACHE_DIR` stub, and the learned toolkit slugs resolve against the
45 +// developer's real `~/.composio`. Suites that assert how a toolkit is learned
46 +// need a cache directory of their own, seeded with the fixture's user data.
47 +const isolatedCacheConfigProvider = (fixture: string) => {
48 + const cacheDir = fs.mkdtempSync(path.join(os.tmpdir(), 'composio-cli-test-cache-'));
49 + fs.cpSync(new URL(`../../../__fixtures__/${fixture}/.composio`, import.meta.url), cacheDir, {
50 + recursive: true,
51 + });
52 + // Fresh learned slugs keep the background catalog refresh from running, so
53 + // every toolkit lookup a suite observes comes from the command itself.
54 + fs.writeFileSync(
55 + path.join(cacheDir, 'known-toolkit-slugs.json'),
56 + JSON.stringify({ slugs: [], refreshedAt: new Date().toISOString() })
57 + );
58 + return ConfigProvider.fromEnv({
59 + env: { COMPOSIO_USER_API_KEY: 'test_api_key', COMPOSIO_CACHE_DIR: cacheDir },
60 + }).pipe(extendConfigProvider);
61 +};
62 +
63 const runInvocationConfigProvider = ConfigProvider.fromEnvRecord({
64 COMPOSIO_USER_API_KEY: 'test_api_key',
65 COMPOSIO_CLI_INVOCATION_ORIGIN: 'run',
@@ -120,8 +140,10 @@ describe('CLI: composio execute', () => {
140 });
141
142 let recordedSessionCreateParams: Array<Record<string, unknown>> = [];
143 + let recordedProjectToolkitScopes: Array<composioClients.ToolkitProjectScope | undefined> = [];
144 beforeEach(() => {
145 recordedSessionCreateParams = [];
146 + recordedProjectToolkitScopes = [];
147 });
148
149 layer(
@@ -630,6 +652,154 @@ describe('CLI: composio execute', () => {
652 );
653 });
654
655 + layer(
656 + TestLive({
657 + baseConfigProvider: isolatedCacheConfigProvider('global-test-user-id'),
658 + fixture: 'global-test-user-id',
659 + stdin: { isTTY: true, data: '' },
660 + toolkitsData: {
661 + // Custom toolkits belong to the project: the Composio-managed catalog
662 + // never lists them, and the baked one cannot.
663 + toolkits: [makeToolkitFixture('gmail', 'Gmail')],
664 + projectToolkits: [makeToolkitFixture('custom_grain', 'Grain')],
665 + // The consumer project execute resolves, not the fixture's developer
666 + // project that the project context would pick without a scope.
667 + projectToolkitsScope: { orgId: 'org_test', projectId: 'consumer_project_test' },
668 + onGetProjectToolkits: scope => recordedProjectToolkitScopes.push(scope),
669 + },
670 + connectedAccountsData: {
671 + items: [
672 + {
673 + id: 'ca_1',
674 + alias: 'grain-work',
675 + word_id: 'lantern',
676 + status: 'ACTIVE',
677 + status_reason: null,
678 + is_disabled: false,
679 + user_id: 'consumer-user-org_test',
680 + toolkit: { slug: 'custom_grain' },
681 + auth_config: {
682 + id: 'ac_custom_grain',
683 + auth_scheme: 'API_KEY',
684 + is_composio_managed: false,
685 + is_disabled: false,
686 + },
687 + created_at: '2026-01-01T00:00:00.000Z',
688 + updated_at: '2026-01-01T00:00:00.000Z',
689 + test_request_endpoint: '',
690 + },
691 + ],
692 + },
693 + toolRouter: {
694 + create: async params => {
695 + recordedSessionCreateParams.push(params as unknown as Record<string, unknown>);
696 + return {
697 + session_id: 'trs_custom_grain_session',
698 + config: {
699 + user_id: params.user_id,
700 + execute: {},
701 + search: {},
702 + preload: { tools: [] },
703 + premium_usage: false,
704 + },
705 + config_version: 1,
706 + mcp: { type: 'http' as const, url: 'https://mcp.test.composio.dev' },
707 + tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'COMPOSIO_MANAGE_CONNECTIONS'],
708 + };
709 + },
710 + execute: async (_sessionId, params) => ({
711 + data: { tool_slug: params.tool_slug, arguments: params.arguments },
712 + error: null,
713 + log_id: 'log_custom_grain',
714 + }),
715 + },
716 + })
717 + )('[Given] a project custom toolkit [Then] execute resolves it from the project list', it => {
718 + const connectedToolkitsCache = (toolkits: ReadonlyArray<string>) => {
719 + vi.spyOn(
720 + consumerShortTermCache,
721 + 'getFreshConsumerConnectedToolkitsFromCache'
722 + ).mockReturnValue(Effect.succeed(Option.some([...toolkits])));
723 + };
724 +
725 + it.effect.each(['ca_1', 'grain-work', 'lantern'])(
726 + 'pins the custom_grain connected account selected by %s',
727 + selector =>
728 + Effect.gen(function* () {
729 + connectedToolkitsCache(['gmail', 'custom_grain']);
730 +
731 + yield* cli([
732 + 'execute',
733 + 'CUSTOM_GRAIN_SEARCH_PERSONS',
734 + '--account',
735 + selector,
736 + '-d',
737 + '{"query":"ada"}',
738 + ]);
739 +
740 + expect(recordedSessionCreateParams[0]?.connected_accounts).toEqual({
741 + custom_grain: 'ca_1',
742 + });
743 + // Every lookup — account selection, the permission gate, error
744 + // mapping — must ask for the project execute resolved.
745 + expect(recordedProjectToolkitScopes.length).toBeGreaterThan(0);
746 + expect(recordedProjectToolkitScopes).toEqual(
747 + recordedProjectToolkitScopes.map(() => ({
748 + orgId: 'org_test',
749 + projectId: 'consumer_project_test',
750 + }))
751 + );
752 + })
753 + );
754 +
755 + it.effect('names the custom toolkit when the selector matches no account', () =>
756 + Effect.gen(function* () {
757 + const failure = yield* cli([
758 + 'execute',
759 + 'CUSTOM_GRAIN_SEARCH_PERSONS',
760 + '--account',
761 + 'nope',
762 + '--skip-connection-check',
763 + '-d',
764 + '{"query":"ada"}',
765 + ]).pipe(Effect.flip);
766 +
767 + expect(String((failure as { message?: unknown }).message)).toContain(
768 + 'No connected account matched "nope" for toolkit "custom_grain". Available accounts:'
769 + );
770 + expect(String((failure as { message?: unknown }).message)).toContain('ca_1');
771 + expect(recordedSessionCreateParams).toHaveLength(0);
772 + })
773 + );
774 +
775 + it.effect('fails the connection pre-check under the custom toolkit slug', () =>
776 + Effect.gen(function* () {
777 + connectedToolkitsCache(['gmail']);
778 +
779 + yield* cli(['execute', 'CUSTOM_GRAIN_SEARCH_PERSONS', '-d', '{"query":"ada"}']).pipe(
780 + Effect.flip
781 + );
782 + const output = (yield* MockConsole.getLines({ stripAnsi: true })).join('\n');
783 +
784 + expect(output).toContain('Toolkit "custom_grain" is not connected for this user');
785 + expect(output).toContain('composio link custom_grain');
786 + expect(recordedSessionCreateParams).toHaveLength(0);
787 + })
788 + );
789 +
790 + it.effect('uses the default custom_grain account without --account', () =>
791 + Effect.gen(function* () {
792 + connectedToolkitsCache(['gmail', 'custom_grain']);
793 +
794 + yield* cli(['execute', 'CUSTOM_GRAIN_SEARCH_PERSONS', '-d', '{"query":"ada"}']);
795 +
796 + expect(recordedSessionCreateParams[0]?.connected_accounts).toEqual({
797 + custom_grain: 'ca_1',
798 + });
799 + })
800 + );
801 + });
802 +
803 layer(
804 TestLive({
805 baseConfigProvider: testConfigProvider,
ts/packages/cli/test/src/commands/tools/tools.list.cmd.test.ts
+35
@@ -182,4 +182,39 @@ describe('CLI: composio tools list', () => {
182 );
183 }
184 );
185 +
186 + layer(TestLive({ baseConfigProvider: testConfigProvider, toolkitsData }))(
187 + '[Given] custom toolkit "custom_grain" with no tools [Then] points at composio search',
188 + it => {
189 + it.effect('suggests searching the custom toolkit through the Tool Router', () =>
190 + Effect.gen(function* () {
191 + yield* cli(['tools', 'list', 'custom_grain']);
192 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
193 + const output = lines.join('\n');
194 +
195 + expect(output).toContain('No tools found');
196 + expect(output).toContain('composio search "<query>" --toolkits custom_grain');
197 + expect(output).not.toContain('composio dev toolkits list');
198 + })
199 + );
200 + }
201 + );
202 +
203 + layer(TestLive({ baseConfigProvider: testConfigProvider }))(
204 + '[Given] native toolkit "gmail" with no tools [Then] keeps the toolkit slug hint',
205 + it => {
206 + it.effect('suggests verifying the toolkit slug', () =>
207 + Effect.gen(function* () {
208 + yield* cli(['tools', 'list', 'gmail']);
209 + const lines = yield* MockConsole.getLines({ stripAnsi: true });
210 + const output = lines.join('\n');
211 +
212 + expect(output).toContain(
213 + 'No tools found in toolkit "gmail". Verify the toolkit slug with:\n> composio dev toolkits list'
214 + );
215 + expect(output).not.toContain('composio search');
216 + })
217 + );
218 + }
219 + );
220 });
ts/packages/cli/test/src/effects/toolkit-from-tool-slug.test.ts
+301 -20
@@ -1,15 +1,20 @@
1 import { describe, expect, it } from '@effect/vitest';
2 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
3 -import { ConfigProvider, DateTime, Effect, FileSystem, Layer, Schedule } from 'effect';
3 +import { ConfigProvider, DateTime, Deferred, Effect, FileSystem, Layer, Schedule } from 'effect';
4 import * as tempy from 'tempy';
5 import { toolkitFromToolSlug } from 'src/effects/toolkit-from-tool-slug';
6 import type { Toolkits } from 'src/models/toolkits';
7 -import { ComposioToolkitsRepository, HttpServerError } from 'src/services/composio-clients';
7 +import {
8 + ComposioToolkitsRepository,
9 + HttpServerError,
10 + type ToolkitProjectScope,
11 +} from 'src/services/composio-clients';
12 import { KNOWN_TOOLKIT_SLUGS_FILE } from 'src/services/known-toolkit-slugs';
13 import { ToolkitSlugCatalog } from 'src/services/toolkit-slug-catalog';
14 import { makeToolkitFixture } from 'test/__utils__/models/toolkits';
15 import {
16 countingToolkitsRepository,
17 + type GetProjectToolkitsError,
18 type GetToolkitsError,
19 } from 'test/__utils__/services/toolkits-repository-stub';
20
@@ -20,6 +25,12 @@ import {
25 */
26 const UNRELEASED_TOOLKIT = 'acme_analytics';
27
28 +/**
29 + * A project-scoped custom toolkit. Custom toolkits never ship in the baked
30 + * catalog, and their slugs share the `custom` prefix with nothing baked.
31 + */
32 +const CUSTOM_TOOLKIT = 'custom_grain';
33 +
34 const failingFetch = () =>
35 Effect.fail(new HttpServerError({ cause: 'catalog unavailable', status: 503 }));
36
@@ -34,8 +45,17 @@ const learnedFileContent = (slugs: ReadonlyArray<string>, daysAgo = 0) =>
45 refreshedAt: DateTime.formatIso(DateTime.subtract(DateTime.nowUnsafe(), { days: daysAgo })),
46 });
47
48 +interface ResolverOptions {
49 + readonly getToolkits?: () => Effect.Effect<Toolkits, GetToolkitsError>;
50 + readonly getProjectToolkits?: (
51 + scope?: ToolkitProjectScope
52 + ) => Effect.Effect<Toolkits, GetProjectToolkitsError>;
53 + readonly seedLearnedFile?: string;
54 +}
55 +
56 interface ResolverContext {
57 readonly calls: () => number;
58 + readonly projectCalls: () => number;
59 readonly waitForLearnedFile: (
60 predicate: (content: string) => boolean
61 ) => Effect.Effect<string, unknown, FileSystem.FileSystem>;
@@ -47,10 +67,7 @@ interface ResolverContext {
67 * is written verbatim — including deliberately corrupt content.
68 */
69 const withResolver = <A>(
50 - options: {
51 - readonly getToolkits?: () => Effect.Effect<Toolkits, GetToolkitsError>;
52 - readonly seedLearnedFile?: string;
53 - },
70 + options: ResolverOptions,
71 program: (
72 context: ResolverContext
73 ) => Effect.Effect<
@@ -66,10 +83,7 @@ const withResolver = <A>(
83
84 const runInCacheDir = <A>(
85 cacheDir: string,
69 - options: {
70 - readonly getToolkits?: () => Effect.Effect<Toolkits, GetToolkitsError>;
71 - readonly seedLearnedFile?: string;
72 - },
86 + options: ResolverOptions,
87 program: (
88 context: ResolverContext
89 ) => Effect.Effect<
@@ -87,13 +101,15 @@ const runInCacheDir = <A>(
101 }
102
103 const repository = countingToolkitsRepository(
90 - options.getToolkits ?? (() => Effect.succeed([] as Toolkits))
104 + options.getToolkits ?? (() => Effect.succeed([] as Toolkits)),
105 + options.getProjectToolkits
106 );
107
108 const readLearnedFile = fs.readFileString(learnedFile);
109
110 return yield* program({
111 calls: repository.calls,
112 + projectCalls: repository.projectCalls,
113 // The resolver records what it learns in the background, so a test that
114 // asserts on the file has to wait for it rather than read once.
115 waitForLearnedFile: predicate =>
@@ -129,7 +145,7 @@ describe('toolkitFromToolSlug', () => {
145 );
146
147 it.effect('gives meta tools no toolkit, even when one shadows their slug', () =>
132 - withResolver({ seedLearnedFile: learnedFileContent([]) }, ({ calls }) =>
148 + withResolver({ seedLearnedFile: learnedFileContent([]) }, ({ calls, projectCalls }) =>
149 Effect.gen(function* () {
150 // `composio_search` is a real, linkable toolkit whose slug is a prefix
151 // of this session meta tool. Attributing the meta tool to it would
@@ -137,6 +153,7 @@ describe('toolkitFromToolSlug', () => {
153 expect(yield* toolkitFromToolSlug('COMPOSIO_SEARCH_TOOLS')).toBeUndefined();
154 expect(yield* toolkitFromToolSlug('COMPOSIO_MANAGE_CONNECTIONS')).toBeUndefined();
155 expect(calls()).toBe(0);
156 + expect(projectCalls()).toBe(0);
157 })
158 )
159 );
@@ -201,18 +218,18 @@ describe('toolkitFromToolSlug', () => {
218 )
219 );
220
204 - it.live('records learned slugs at most once per run', () =>
221 + it.live('merges later recordings in a run instead of dropping them', () =>
222 withResolver({ seedLearnedFile: learnedFileContent([]) }, ({ waitForLearnedFile }) =>
223 Effect.gen(function* () {
224 const catalog = yield* ToolkitSlugCatalog;
208 - // Every miss in a run merges the same memoized fetch, so a second
209 - // recording could only rewrite the same file. Passing a different list
210 - // here makes the gate observable: its slugs must never land.
225 + // Misses in one run can see different catalogs — an unscoped startup
226 + // lookup, then the command's project — so a later recording that
227 + // brings new slugs must land alongside the first one.
228 yield* catalog.remember([UNRELEASED_TOOLKIT]);
212 - yield* catalog.remember(['slug_from_a_second_recording']);
229 + yield* catalog.remember([UNRELEASED_TOOLKIT, CUSTOM_TOOLKIT]);
230
214 - const learned = yield* waitForLearnedFile(content => content.includes(UNRELEASED_TOOLKIT));
215 - expect(learned).not.toContain('slug_from_a_second_recording');
231 + const learned = yield* waitForLearnedFile(content => content.includes(CUSTOM_TOOLKIT));
232 + expect(learned).toContain(UNRELEASED_TOOLKIT);
233 })
234 )
235 );
@@ -256,7 +273,7 @@ describe('toolkitFromToolSlug', () => {
273 const learned = yield* waitForLearnedFile(content =>
274 content.includes(UNRELEASED_TOOLKIT)
275 );
259 - expect(learned).not.toContain('stale_toolkit');
276 + expect(learned).toContain('stale_toolkit');
277 })
278 )
279 );
@@ -297,4 +314,268 @@ describe('toolkitFromToolSlug', () => {
314 })
315 )
316 );
317 + describe('project-managed custom toolkits', () => {
318 + it.live('resolves a custom toolkit from the project catalog, and remembers it', () =>
319 + withResolver(
320 + {
321 + getProjectToolkits: () => Effect.succeed([makeToolkitFixture(CUSTOM_TOOLKIT)]),
322 + seedLearnedFile: learnedFileContent([]),
323 + },
324 + ({ calls, projectCalls, waitForLearnedFile }) =>
325 + Effect.gen(function* () {
326 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(CUSTOM_TOOLKIT);
327 + expect(calls()).toBe(1);
328 + expect(projectCalls()).toBe(1);
329 +
330 + yield* waitForLearnedFile(content => content.includes(CUSTOM_TOOLKIT));
331 + })
332 + )
333 + );
334 +
335 + it.live('uses a remembered custom toolkit when the project catalog is unreachable', () =>
336 + withResolver(
337 + {
338 + getToolkits: failingFetch,
339 + getProjectToolkits: failingFetch,
340 + seedLearnedFile: learnedFileContent([CUSTOM_TOOLKIT]),
341 + },
342 + ({ calls, projectCalls }) =>
343 + Effect.gen(function* () {
344 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(CUSTOM_TOOLKIT);
345 + expect(calls()).toBe(1);
346 + expect(projectCalls()).toBe(1);
347 + })
348 + )
349 + );
350 +
351 + for (const learned of ['custom_grain', 'custom_grain_search_persons']) {
352 + it.live(`uses the active project's prefix instead of learned ${learned}`, () =>
353 + withResolver(
354 + {
355 + seedLearnedFile: learnedFileContent([learned]),
356 + getProjectToolkits: scope =>
357 + Effect.succeed(
358 + scope?.projectId === 'proj_b' ? [makeToolkitFixture('custom_grain_search')] : []
359 + ),
360 + },
361 + () =>
362 + Effect.gen(function* () {
363 + expect(
364 + yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS_LIST', {
365 + orgId: 'org_1',
366 + projectId: 'proj_b',
367 + })
368 + ).toBe('custom_grain_search');
369 + expect(
370 + yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS_LIST', {
371 + orgId: 'org_1',
372 + projectId: 'proj_empty',
373 + })
374 + ).toBe('custom');
375 + })
376 + )
377 + );
378 + }
379 +
380 + it.live('keeps a scoped discovery when an older background fetch completes later', () =>
381 + Effect.gen(function* () {
382 + const releaseRefresh = yield* Deferred.make<void>();
383 + yield* withResolver(
384 + {
385 + seedLearnedFile: learnedFileContent([], 8),
386 + getToolkits: () =>
387 + Deferred.await(releaseRefresh).pipe(
388 + Effect.as([makeToolkitFixture(UNRELEASED_TOOLKIT)])
389 + ),
390 + },
391 + ({ waitForLearnedFile }) =>
392 + Effect.gen(function* () {
393 + expect(yield* toolkitFromToolSlug('GMAIL_SEND_EMAIL')).toBe('gmail');
394 + const catalog = yield* ToolkitSlugCatalog;
395 + yield* catalog.remember([CUSTOM_TOOLKIT]);
396 + yield* waitForLearnedFile(content => content.includes(CUSTOM_TOOLKIT));
397 + yield* Deferred.succeed(releaseRefresh, undefined);
398 + const learned = yield* waitForLearnedFile(content =>
399 + content.includes(UNRELEASED_TOOLKIT)
400 + );
401 + expect(learned).toContain(CUSTOM_TOOLKIT);
402 + })
403 + );
404 + })
405 + );
406 +
407 + it.live('retries a stale native catalog after remembering a partial project result', () =>
408 + Effect.gen(function* () {
409 + const cacheDir = tempy.temporaryDirectory();
410 + const seed = learnedFileContent([], 8);
411 + yield* runInCacheDir(
412 + cacheDir,
413 + {
414 + seedLearnedFile: seed,
415 + getToolkits: failingFetch,
416 + getProjectToolkits: () => Effect.succeed([makeToolkitFixture(CUSTOM_TOOLKIT)]),
417 + },
418 + ({ waitForLearnedFile }) =>
419 + Effect.gen(function* () {
420 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(
421 + CUSTOM_TOOLKIT
422 + );
423 + const learned = yield* waitForLearnedFile(content =>
424 + content.includes(CUSTOM_TOOLKIT)
425 + );
426 + expect(JSON.parse(learned).refreshedAt).toBe(JSON.parse(seed).refreshedAt);
427 + })
428 + );
429 + yield* runInCacheDir(
430 + cacheDir,
431 + {
432 + getToolkits: () => Effect.succeed([makeToolkitFixture(UNRELEASED_TOOLKIT)]),
433 + },
434 + ({ waitForLearnedFile }) =>
435 + Effect.gen(function* () {
436 + expect(yield* toolkitFromToolSlug('GMAIL_SEND_EMAIL')).toBe('gmail');
437 + const learned = yield* waitForLearnedFile(content =>
438 + content.includes(UNRELEASED_TOOLKIT)
439 + );
440 + expect(learned).toContain(CUSTOM_TOOLKIT);
441 + expect(JSON.parse(learned).refreshedAt).not.toBe(JSON.parse(seed).refreshedAt);
442 + })
443 + );
444 + })
445 + );
446 +
447 + it.live('preserves learned custom slugs when an unscoped refresh cannot list them', () =>
448 + withResolver(
449 + {
450 + seedLearnedFile: learnedFileContent([CUSTOM_TOOLKIT], 8),
451 + getToolkits: () => Effect.succeed([makeToolkitFixture(UNRELEASED_TOOLKIT)]),
452 + getProjectToolkits: failingFetch,
453 + },
454 + ({ waitForLearnedFile }) =>
455 + Effect.gen(function* () {
456 + expect(yield* toolkitFromToolSlug('GMAIL_SEND_EMAIL')).toBe('gmail');
457 + const learned = yield* waitForLearnedFile(content =>
458 + content.includes(UNRELEASED_TOOLKIT)
459 + );
460 + expect(learned).toContain(CUSTOM_TOOLKIT);
461 + })
462 + )
463 + );
464 +
465 + it.live('keeps resolving baked `custom*` toolkits locally', () =>
466 + withResolver(
467 + { seedLearnedFile: learnedFileContent([CUSTOM_TOOLKIT]) },
468 + ({ calls, projectCalls }) =>
469 + Effect.gen(function* () {
470 + expect(yield* toolkitFromToolSlug('CUSTOMERIO_SEND_EVENT')).toBe('customerio');
471 + expect(calls()).toBe(0);
472 + expect(projectCalls()).toBe(0);
473 + })
474 + )
475 + );
476 +
477 + it.live('prefers the longest custom toolkit prefix', () =>
478 + withResolver(
479 + {
480 + getProjectToolkits: () =>
481 + Effect.succeed([
482 + makeToolkitFixture(CUSTOM_TOOLKIT),
483 + makeToolkitFixture(`${CUSTOM_TOOLKIT}_search`),
484 + ]),
485 + seedLearnedFile: learnedFileContent([]),
486 + },
487 + () =>
488 + Effect.gen(function* () {
489 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(
490 + `${CUSTOM_TOOLKIT}_search`
491 + );
492 + })
493 + )
494 + );
495 +
496 + it.live('still resolves native toolkits when the project catalog is unreachable', () =>
497 + withResolver(
498 + {
499 + getToolkits: () => Effect.succeed([makeToolkitFixture(UNRELEASED_TOOLKIT)]),
500 + getProjectToolkits: failingFetch,
501 + seedLearnedFile: learnedFileContent([]),
502 + },
503 + () =>
504 + Effect.gen(function* () {
505 + expect(yield* toolkitFromToolSlug('ACME_ANALYTICS_RUN_REPORT')).toBe(
506 + UNRELEASED_TOOLKIT
507 + );
508 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe('custom');
509 + })
510 + )
511 + );
512 +
513 + it.live('resolves custom toolkits when only the native catalog is unreachable', () =>
514 + withResolver(
515 + {
516 + getToolkits: failingFetch,
517 + getProjectToolkits: () => Effect.succeed([makeToolkitFixture(CUSTOM_TOOLKIT)]),
518 + seedLearnedFile: learnedFileContent([]),
519 + },
520 + () =>
521 + Effect.gen(function* () {
522 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(CUSTOM_TOOLKIT);
523 + })
524 + )
525 + );
526 +
527 + it.live('guesses, and records nothing, when both catalogs are unreachable', () => {
528 + const seed = learnedFileContent([]);
529 + return withResolver(
530 + {
531 + getToolkits: failingFetch,
532 + getProjectToolkits: failingFetch,
533 + seedLearnedFile: seed,
534 + },
535 + ({ waitForLearnedFile }) =>
536 + Effect.gen(function* () {
537 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe('custom');
538 + yield* Effect.sleep('50 millis');
539 + expect(yield* waitForLearnedFile(() => true)).toBe(seed);
540 + })
541 + );
542 + });
543 +
544 + it.live('learns a custom toolkit found by a scoped lookup after an unscoped one', () =>
545 + withResolver(
546 + {
547 + getProjectToolkits: scope =>
548 + Effect.succeed(scope ? [makeToolkitFixture(CUSTOM_TOOLKIT)] : []),
549 + seedLearnedFile: learnedFileContent([]),
550 + },
551 + ({ waitForLearnedFile }) =>
552 + Effect.gen(function* () {
553 + // Startup telemetry resolves before the command knows its project.
554 + expect(yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe('custom');
555 + expect(
556 + yield* toolkitFromToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS', {
557 + orgId: 'org_1',
558 + projectId: 'proj_1',
559 + })
560 + ).toBe(CUSTOM_TOOLKIT);
561 +
562 + yield* waitForLearnedFile(content => content.includes(CUSTOM_TOOLKIT));
563 + })
564 + )
565 + );
566 +
567 + it.live('includes project toolkits in the background refresh', () =>
568 + withResolver(
569 + {
570 + getProjectToolkits: () => Effect.succeed([makeToolkitFixture(CUSTOM_TOOLKIT)]),
571 + seedLearnedFile: learnedFileContent(['stale_toolkit'], 8),
572 + },
573 + ({ waitForLearnedFile }) =>
574 + Effect.gen(function* () {
575 + expect(yield* toolkitFromToolSlug('GMAIL_SEND_EMAIL')).toBe('gmail');
576 + yield* waitForLearnedFile(content => content.includes(CUSTOM_TOOLKIT));
577 + })
578 + )
579 + );
580 + });
581 });
ts/packages/cli/test/src/models/toolkits.test.ts
+82 -2
@@ -1,7 +1,7 @@
1 import { describe, expect, it } from '@effect/vitest';
2 -import { Effect } from 'effect';
2 +import { Effect, Schema } from 'effect';
3 import toolkitsJson from 'test/__mocks__/toolkits.json' with { type: 'json' };
4 -import { toolkitsFromJSON } from 'src/models/toolkits';
4 +import { Toolkits, toolkitsFromJSON, toolkitsToJSON } from 'src/models/toolkits';
5
6 describe('ToolkitSlug', () => {
7 it.effect(
@@ -15,3 +15,83 @@ describe('ToolkitSlug', () => {
15 })
16 );
17 });
18 +
19 +describe('Toolkit', () => {
20 + const meta = {
21 + description: 'Project custom toolkit',
22 + categories: [],
23 + created_at: '2025-01-01T00:00:00.000Z',
24 + updated_at: '2025-01-02T00:00:00.000Z',
25 + logo: '',
26 + tools_count: 2,
27 + triggers_count: 0,
28 + version: '20250101_00',
29 + };
30 +
31 + it.effect(
32 + '[Given] a project custom toolkit without auth fields [Then] it decodes with empty auth defaults',
33 + Effect.fn(function* () {
34 + const [toolkit] = yield* Schema.decodeUnknownEffect(Toolkits)([
35 + {
36 + slug: 'custom_grain',
37 + name: 'Grain',
38 + type: 'custom',
39 + is_local_toolkit: false,
40 + deprecated: false,
41 + meta,
42 + },
43 + ]);
44 +
45 + expect(toolkit.slug).toBe('custom_grain');
46 + expect(toolkit.auth_schemes).toEqual([]);
47 + expect(toolkit.composio_managed_auth_schemes).toEqual([]);
48 + expect(toolkit.no_auth).toBe(false);
49 + })
50 + );
51 +
52 + it.effect(
53 + '[Given] a native toolkit with auth fields [Then] it keeps the provided values',
54 + Effect.fn(function* () {
55 + const [toolkit] = yield* Schema.decodeUnknownEffect(Toolkits)([
56 + {
57 + slug: 'gmail',
58 + name: 'Gmail',
59 + is_local_toolkit: false,
60 + auth_schemes: ['OAUTH2', 'BEARER_TOKEN'],
61 + composio_managed_auth_schemes: ['OAUTH2'],
62 + no_auth: true,
63 + meta,
64 + },
65 + ]);
66 +
67 + expect(toolkit.auth_schemes).toEqual(['OAUTH2', 'BEARER_TOKEN']);
68 + expect(toolkit.composio_managed_auth_schemes).toEqual(['OAUTH2']);
69 + expect(toolkit.no_auth).toBe(true);
70 + })
71 + );
72 +
73 + it.effect(
74 + '[Given] decoded toolkits including a defaulted custom toolkit [Then] the JSON cache round-trip keeps values',
75 + Effect.fn(function* () {
76 + const toolkits = yield* Schema.decodeUnknownEffect(Toolkits)([
77 + { slug: 'custom_grain', name: 'Grain', is_local_toolkit: false, meta },
78 + {
79 + slug: 'gmail',
80 + name: 'Gmail',
81 + is_local_toolkit: false,
82 + auth_schemes: ['OAUTH2'],
83 + composio_managed_auth_schemes: ['OAUTH2'],
84 + no_auth: false,
85 + meta,
86 + },
87 + ]);
88 +
89 + const roundTripped = yield* toolkitsFromJSON(yield* toolkitsToJSON(toolkits));
90 +
91 + expect(roundTripped).toEqual(toolkits);
92 + expect(roundTripped[0]?.auth_schemes).toEqual([]);
93 + expect(roundTripped[0]?.no_auth).toBe(false);
94 + expect(roundTripped[1]?.auth_schemes).toEqual(['OAUTH2']);
95 + })
96 + );
97 +});
ts/packages/cli/test/src/services/command-hints.test.ts
+7
@@ -31,6 +31,13 @@ describe('command-hints', () => {
31 '--get-schema'
32 );
33 expect(commandHintExample('dev.logs.tools', { logId: 'log_123' })).toContain('log_123');
34 + expect(commandHintExample('root.search')).toBe('composio search "<query>"');
35 + expect(commandHintExample('root.search', { query: 'send email' })).toBe(
36 + 'composio search "send email"'
37 + );
38 + expect(commandHintExample('root.search', { toolkits: 'custom_grain' })).toBe(
39 + 'composio search "<query>" --toolkits custom_grain'
40 + );
41 });
42
43 it('serializes the graph with nodes and links', () => {
ts/packages/cli/test/src/services/composio-clients-cached.test.ts
+100 -5
@@ -1,7 +1,11 @@
1 import { describe, expect, it } from '@effect/vitest';
2 import { ConfigProvider, DateTime, Effect, Layer } from 'effect';
3 import * as tempy from 'tempy';
4 -import { ComposioToolkitsRepository, HttpServerError } from 'src/services/composio-clients';
4 +import {
5 + ComposioToolkitsRepository,
6 + HttpServerError,
7 + type ToolkitProjectScope,
8 +} from 'src/services/composio-clients';
9 import * as FileSystem from 'effect/FileSystem';
10 import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
11 import {
@@ -12,6 +16,7 @@ import { toolkitsToJSON, type Toolkits } from 'src/models/toolkits';
16 import { makeToolkitFixture } from 'test/__utils__/models/toolkits';
17 import {
18 countingToolkitsRepository,
19 + type GetProjectToolkitsError,
20 type GetToolkitsError,
21 } from 'test/__utils__/services/toolkits-repository-stub';
22
@@ -27,15 +32,27 @@ const withCountingRepository = <A>(
32 getToolkits: () => Effect.Effect<Toolkits, GetToolkitsError>,
33 program: (context: {
34 readonly calls: () => number;
35 + readonly projectCalls: () => number;
36 readonly cacheDir: string;
31 - }) => Effect.Effect<A, GetToolkitsError, ComposioToolkitsRepository | FileSystem.FileSystem>,
32 - config: ReadonlyArray<readonly [string, string]> = []
37 + }) => Effect.Effect<
38 + A,
39 + GetToolkitsError | GetProjectToolkitsError,
40 + ComposioToolkitsRepository | FileSystem.FileSystem
41 + >,
42 + config: ReadonlyArray<readonly [string, string]> = [],
43 + getProjectToolkits?: (
44 + scope?: ToolkitProjectScope
45 + ) => Effect.Effect<Toolkits, GetProjectToolkitsError>
46 ) =>
47 Effect.suspend(() => {
48 const cacheDir = tempy.temporaryDirectory();
36 - const repository = countingToolkitsRepository(getToolkits);
49 + const repository = countingToolkitsRepository(getToolkits, getProjectToolkits);
50
38 - return program({ calls: repository.calls, cacheDir }).pipe(
51 + return program({
52 + calls: repository.calls,
53 + projectCalls: repository.projectCalls,
54 + cacheDir,
55 + }).pipe(
56 Effect.provide(
57 Layer.merge(
58 Layer.provide(ComposioToolkitsRepositoryCached, repository.layer),
@@ -131,4 +148,82 @@ describe('ComposioToolkitsRepositoryCached', () => {
148 [['FORCE_USE_CACHE', 'true']]
149 )
150 );
151 +
152 + it.effect('fetches project toolkits once, and never from the cached file', () =>
153 + withCountingRepository(
154 + () => Effect.die('the cached file should have answered this'),
155 + ({ calls, projectCalls, cacheDir }) =>
156 + Effect.gen(function* () {
157 + const fs = yield* FileSystem.FileSystem;
158 + const cacheFile = `${cacheDir}/${CACHE_FILES.toolkits}`;
159 + const cached = yield* toolkitsToJSON(testToolkits).pipe(Effect.orDie);
160 + yield* fs.writeFileString(cacheFile, cached).pipe(Effect.orDie);
161 +
162 + const repository = yield* ComposioToolkitsRepository;
163 + const toolkits = yield* repository.getToolkits();
164 + const projectToolkits = yield* repository.getProjectToolkits();
165 + yield* repository.getProjectToolkits();
166 +
167 + expect(toolkits.map(t => t.slug)).toEqual(['github', 'gmail']);
168 + expect(projectToolkits.map(t => t.slug)).toEqual(['custom_grain']);
169 + expect(calls()).toBe(0);
170 + expect(projectCalls()).toBe(1);
171 + // `toolkits.json` holds the Composio-managed catalog only.
172 + expect(yield* fs.readFileString(cacheFile).pipe(Effect.orDie)).toBe(cached);
173 + }),
174 + [['FORCE_USE_CACHE', 'true']],
175 + () => Effect.succeed([makeToolkitFixture('custom_grain')])
176 + )
177 + );
178 +
179 + it.effect('surfaces a failed project fetch once, and does not retry it', () =>
180 + withCountingRepository(
181 + () => Effect.die('the project lookup should not read the catalog'),
182 + ({ projectCalls }) =>
183 + Effect.gen(function* () {
184 + const repository = yield* ComposioToolkitsRepository;
185 + const scope = { orgId: 'org_a', projectId: 'pr_a' };
186 +
187 + const first = yield* Effect.result(repository.getProjectToolkits(scope));
188 + const second = yield* Effect.result(repository.getProjectToolkits(scope));
189 +
190 + expect(second).toEqual(first);
191 + expect(projectCalls()).toBe(1);
192 + }),
193 + [],
194 + () => Effect.fail(new HttpServerError({ cause: 'network down', status: 503 }))
195 + )
196 + );
197 +
198 + it.effect('fetches project toolkits once per project scope', () =>
199 + withCountingRepository(
200 + () => Effect.die('the project lookup should not read the catalog'),
201 + ({ projectCalls }) =>
202 + Effect.gen(function* () {
203 + const repository = yield* ComposioToolkitsRepository;
204 + const scopeA = { orgId: 'org_a', projectId: 'pr_a' };
205 + const scopeB = { orgId: 'org_a', projectId: 'pr_b' };
206 +
207 + const results = yield* Effect.all([
208 + repository.getProjectToolkits(scopeA),
209 + repository.getProjectToolkits(scopeB),
210 + repository.getProjectToolkits({ ...scopeA }),
211 + repository.getProjectToolkits(scopeB),
212 + repository.getProjectToolkits(),
213 + ]);
214 +
215 + expect(results.map(toolkits => toolkits.map(t => t.slug))).toEqual([
216 + ['custom_pr_a'],
217 + ['custom_pr_b'],
218 + ['custom_pr_a'],
219 + ['custom_pr_b'],
220 + ['custom_unscoped'],
221 + ]);
222 + // Unscoped is a scope of its own: the project context decides it.
223 + expect(projectCalls()).toBe(3);
224 + }),
225 + [],
226 + scope => Effect.succeed([makeToolkitFixture(`custom_${scope?.projectId ?? 'unscoped'}`)])
227 + )
228 + );
229 });
ts/packages/cli/test/src/services/composio-clients.test.ts
+91 -2
@@ -1,7 +1,15 @@
1 import { describe, expect, it } from '@effect/vitest';
2 import { afterEach, vi } from 'vitest';
3 -import { Effect } from 'effect';
4 -import { getSessionInfoByUserApiKey } from 'src/services/composio-clients';
3 +import * as BunFileSystem from '@effect/platform-bun/BunFileSystem';
4 +import * as BunPath from '@effect/platform-bun/BunPath';
5 +import { ConfigProvider, Effect, Layer } from 'effect';
6 +import * as tempy from 'tempy';
7 +import {
8 + ComposioToolkitsRepository,
9 + getSessionInfoByUserApiKey,
10 +} from 'src/services/composio-clients';
11 +import { defaultNodeOs, NodeOs } from 'src/services/node-os';
12 +import { extendConfigProvider } from 'src/services/config';
13
14 const emptyOkResponse = () =>
15 new Response(JSON.stringify({}), {
@@ -55,3 +63,84 @@ describe('getSessionInfoByUserApiKey org context', () => {
63 })
64 );
65 });
66 +
67 +describe('ComposioToolkitsRepository toolkit lists', () => {
68 + afterEach(() => {
69 + vi.restoreAllMocks();
70 + });
71 +
72 + // The real repository over the real client, with no `ProjectContext`: the
73 + // consumer-mode setup, where only an explicit scope names a project.
74 + const repositoryLayer = () =>
75 + Layer.provide(
76 + ComposioToolkitsRepository.Default,
77 + Layer.mergeAll(
78 + BunFileSystem.layer,
79 + BunPath.layer,
80 + Layer.succeed(NodeOs, defaultNodeOs({ homedir: tempy.temporaryDirectory() })),
81 + Layer.succeed(
82 + ConfigProvider.ConfigProvider,
83 + extendConfigProvider(
84 + ConfigProvider.fromEnv({
85 + env: {
86 + COMPOSIO_USER_API_KEY: 'uak_test',
87 + COMPOSIO_BASE_URL: 'https://backend.composio.dev',
88 + },
89 + })
90 + )
91 + )
92 + )
93 + );
94 +
95 + // An empty last page: what is asserted is the request, not the decoding.
96 + const spyOnToolkitsFetch = () =>
97 + vi.spyOn(globalThis, 'fetch').mockImplementation(
98 + async () =>
99 + new Response(JSON.stringify({ items: [], total_pages: 1, next_cursor: null }), {
100 + status: 200,
101 + headers: { 'Content-Type': 'application/json' },
102 + })
103 + );
104 +
105 + const requestOf = (fetchSpy: ReturnType<typeof spyOnToolkitsFetch>) => {
106 + const [input, init] = fetchSpy.mock.calls[0]!;
107 + const url = new URL(input instanceof Request ? input.url : String(input));
108 + const headers = new Headers(input instanceof Request ? input.headers : undefined);
109 + new Headers(init?.headers).forEach((value, key) => headers.set(key, value));
110 + return { url, headers };
111 + };
112 +
113 + it.effect(
114 + '[Given] a scope [Then] getProjectToolkits lists managed_by=project for that project',
115 + () =>
116 + Effect.gen(function* () {
117 + const fetchSpy = spyOnToolkitsFetch();
118 + const repository = yield* ComposioToolkitsRepository;
119 +
120 + yield* repository.getProjectToolkits({ orgId: 'org_scoped', projectId: 'pr_scoped' });
121 +
122 + expect(fetchSpy).toHaveBeenCalledOnce();
123 + const { url, headers } = requestOf(fetchSpy);
124 + expect(url.pathname).toBe('/api/v3.1/toolkits');
125 + expect(url.searchParams.get('managed_by')).toBe('project');
126 + expect(headers.get('x-org-id')).toBe('org_scoped');
127 + expect(headers.get('x-project-id')).toBe('pr_scoped');
128 + }).pipe(Effect.provide(repositoryLayer()))
129 + );
130 +
131 + it.effect('[Given] no scope [Then] getToolkits lists without managed_by or a project', () =>
132 + Effect.gen(function* () {
133 + const fetchSpy = spyOnToolkitsFetch();
134 + const repository = yield* ComposioToolkitsRepository;
135 +
136 + yield* repository.getToolkits();
137 +
138 + expect(fetchSpy).toHaveBeenCalledOnce();
139 + const { url, headers } = requestOf(fetchSpy);
140 + expect(url.pathname).toBe('/api/v3.1/toolkits');
141 + expect(url.searchParams.has('managed_by')).toBe(false);
142 + expect(headers.has('x-org-id')).toBe(false);
143 + expect(headers.has('x-project-id')).toBe(false);
144 + }).pipe(Effect.provide(repositoryLayer()))
145 + );
146 +});
ts/packages/cli/test/src/utils/remote-custom-toolkit.test.ts new
+25
@@ -0,0 +1,25 @@
1 +import { describe, expect, it } from '@effect/vitest';
2 +import { isRemoteCustomToolkitSlug, isRemoteCustomToolSlug } from 'src/utils/remote-custom-toolkit';
3 +
4 +describe('isRemoteCustomToolkitSlug', () => {
5 + it.each(['custom_grain', 'CUSTOM_GRAIN', 'custom_x_y'])('matches %s', slug => {
6 + expect(isRemoteCustomToolkitSlug(slug)).toBe(true);
7 + });
8 +
9 + it.each(['custom', 'custom_', 'customerio', 'customerio_mcp', 'customgpt', 'customjs', 'gmail'])(
10 + 'does not match %s',
11 + slug => {
12 + expect(isRemoteCustomToolkitSlug(slug)).toBe(false);
13 + }
14 + );
15 +});
16 +
17 +describe('isRemoteCustomToolSlug', () => {
18 + it('matches tools of a remote custom toolkit', () => {
19 + expect(isRemoteCustomToolSlug('CUSTOM_GRAIN_SEARCH_PERSONS')).toBe(true);
20 + });
21 +
22 + it('does not match tools of native toolkits whose slug starts with "custom"', () => {
23 + expect(isRemoteCustomToolSlug('CUSTOMERIO_SEND_EVENT')).toBe(false);
24 + });
25 +});