Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Pass link aliases through tool router session creation (#3228)
## Summary - Pass `--alias` through tool router session creation so linked accounts keep their alias without a follow-up patch. - Enable multi-account mode for alias-driven links and exclude the linked toolkit from inherited connected-account pins. - Refresh CLI docs and generated metadata to reflect the updated multi-account behavior and session schema. ## Testing - Added/updated CLI tests for alias handling in `connected-accounts link`. - Updated singleton/header tests to match the removed client header behavior. - Not run
Rahul Tarak committed
Apr 16, 2026 at 15:45 UTC
450538cd1c75acbc5219f05a2a731ffd3ecd6617
3 files changed
+91
-57
ts/packages/cli/src/commands/connected-accounts/commands/connected-accounts.link.cmd.ts
+29
-43
@@ -224,6 +224,20 @@ const getConsumerCacheScope = (resolvedProject: {
224
225
const normalizeAlias = (rawAlias: string) => rawAlias.trim();
226
227
+const resolveNormalizedAliasOption = (alias: Option.Option<string>) =>
228
+ Effect.gen(function* () {
229
+ if (Option.isNone(alias)) {
230
+ return Option.none<string>();
231
+ }
232
+
233
+ const normalizedAlias = normalizeAlias(alias.value);
234
+ if (normalizedAlias.length === 0) {
235
+ return yield* Effect.fail(new Error('`--alias` cannot be empty.'));
236
+ }
237
+
238
+ return Option.some(normalizedAlias);
239
+ });
240
+
241
const listActiveConnectedAccounts = (params: {
242
readonly client: RawComposioClient;
243
readonly userId: string;
@@ -289,32 +303,6 @@ const ensureAliasForAdditionalAccount = (params: {
303
return false as const;
304
});
305
292
-const patchConnectedAccountAlias = (params: {
293
- readonly ui: TerminalUI;
294
- readonly client: RawComposioClient;
295
- readonly connectedAccountId: string;
296
- readonly alias: Option.Option<string>;
297
-}) =>
298
- Effect.gen(function* () {
299
- if (Option.isNone(params.alias)) {
300
- return;
301
- }
302
-
303
- const normalizedAlias = normalizeAlias(params.alias.value);
304
- if (normalizedAlias.length === 0) {
305
- return yield* Effect.fail(new Error('`--alias` cannot be empty.'));
306
- }
307
-
308
- yield* params.ui.withSpinner(
309
- `Assigning alias "${normalizedAlias}"...`,
310
- Effect.tryPromise(() =>
311
- params.client.patch(`/api/v3/connected_accounts/${params.connectedAccountId}`, {
312
- body: { alias: normalizedAlias },
313
- })
314
- )
315
- );
316
- });
317
-
306
const resolveLinkUserId = (params: {
307
readonly resolvedProject: {
308
readonly projectType: 'CONSUMER' | 'DEVELOPER';
@@ -533,6 +521,7 @@ const handleLegacyAuthConfigLink = (params: {
521
orgId: resolvedProject.orgId,
522
projectId: resolvedProject.projectId,
523
});
524
+ const normalizedAlias = yield* resolveNormalizedAliasOption(params.alias);
525
const existingAccounts = yield* listActiveConnectedAccounts({
526
client,
527
userId: resolvedUserId.value,
@@ -545,6 +534,7 @@ const handleLegacyAuthConfigLink = (params: {
534
client.link.create({
535
auth_config_id: params.authConfigId,
536
user_id: resolvedUserId.value,
537
+ ...(Option.isSome(normalizedAlias) && { alias: normalizedAlias.value }),
538
})
539
)
540
)
@@ -572,20 +562,13 @@ const handleLegacyAuthConfigLink = (params: {
562
const { connectedAccountId, redirectUrl } = validatedLink.value;
563
const canContinue = yield* ensureAliasForAdditionalAccount({
564
ui: params.ui,
575
- alias: params.alias,
565
+ alias: normalizedAlias,
566
connectedAccountId,
567
existingAccounts,
568
scopeDescription: `user "${resolvedUserId.value}" in auth config "${params.authConfigId}"`,
569
});
570
if (!canContinue) return;
571
582
- yield* patchConnectedAccountAlias({
583
- ui: params.ui,
584
- client,
585
- connectedAccountId,
586
- alias: params.alias,
587
- });
588
-
572
if (params.noWait) {
573
yield* showRedirectUrl(params.ui, redirectUrl);
574
yield* params.ui.output(
@@ -627,6 +610,7 @@ const runConnectedAccountsLink = (params: {
610
)
611
? params.alias
612
: Option.none<string>();
613
+ const normalizedAliasOption = yield* resolveNormalizedAliasOption(aliasOption);
614
615
const ui = yield* TerminalUI;
616
const clientSingleton = yield* ComposioClientSingleton;
@@ -729,9 +713,18 @@ const runConnectedAccountsLink = (params: {
713
const { sessionId } = yield* resolveToolRouterSession(client, resolvedUserId.value, {
714
manageConnections: true,
715
cacheScope: getConsumerCacheScope(resolvedProject),
716
+ excludeConnectedAccountsForToolkits: [toolkitSlug],
717
+ multiAccount: Option.isSome(normalizedAliasOption)
718
+ ? {
719
+ enable: true,
720
+ }
721
+ : undefined,
722
});
723
return yield* Effect.tryPromise(() =>
734
- client.toolRouter.session.link(sessionId, { toolkit: toolkitSlug })
724
+ client.toolRouter.session.link(sessionId, {
725
+ toolkit: toolkitSlug,
726
+ ...(Option.isSome(normalizedAliasOption) && { alias: normalizedAliasOption.value }),
727
+ })
728
);
729
})
730
)
@@ -767,20 +760,13 @@ const runConnectedAccountsLink = (params: {
760
const { connectedAccountId: connAccountId, redirectUrl } = validatedLink.value;
761
const canContinue = yield* ensureAliasForAdditionalAccount({
762
ui,
770
- alias: aliasOption,
763
+ alias: normalizedAliasOption,
764
connectedAccountId: connAccountId,
765
existingAccounts,
766
scopeDescription: `user "${resolvedUserId.value}" in toolkit "${toolkitSlug}"`,
767
});
768
if (!canContinue) return;
769
777
- yield* patchConnectedAccountAlias({
778
- ui,
779
- client,
780
- connectedAccountId: connAccountId,
781
- alias: aliasOption,
782
- });
783
-
770
if (params.noWait) {
771
yield* showRedirectUrl(ui, redirectUrl);
772
yield* ui.output(
ts/packages/cli/src/effects/create-tool-router-session.ts
+31
-4
@@ -19,6 +19,14 @@ export interface CreateToolRouterSessionOptions {
19
};
20
/** Explicit connected-account pins by toolkit slug. */
21
readonly connectedAccounts?: Record<string, string>;
22
+ /** Toolkits whose connected-account pins should be omitted from the session. */
23
+ readonly excludeConnectedAccountsForToolkits?: ReadonlyArray<string>;
24
+ /** Enable Tool Router multi-account mode for this session. */
25
+ readonly multiAccount?: {
26
+ readonly enable?: boolean;
27
+ readonly maxAccountsPerToolkit?: number;
28
+ readonly requireExplicitSelection?: boolean;
29
+ };
30
}
31
32
/**
@@ -39,6 +47,16 @@ export const createToolRouterSession = (
47
const merged = Object.assign({}, ...mappings.filter(Boolean));
48
return Object.keys(merged).length > 0 ? merged : undefined;
49
};
50
+ const excludedToolkits = new Set(
51
+ (options?.excludeConnectedAccountsForToolkits ?? []).map(toolkit => toolkit.toLowerCase())
52
+ );
53
+ const filterConnectedAccounts = (mapping: Record<string, string> | undefined) => {
54
+ if (!mapping) return undefined;
55
+ const filtered = Object.fromEntries(
56
+ Object.entries(mapping).filter(([toolkit]) => !excludedToolkits.has(toolkit.toLowerCase()))
57
+ );
58
+ return Object.keys(filtered).length > 0 ? filtered : undefined;
59
+ };
60
61
const cachedAuthConfigs = options?.cacheScope
62
? yield* getFreshConsumerToolRouterAuthConfigsFromCache({
@@ -60,9 +78,11 @@ export const createToolRouterSession = (
78
connectedToolkits: options?.toolkits ?? [],
79
authConfigs: cachedAuthConfigs.value.authConfigs,
80
connectedAccounts: mergeConnectedAccounts(
63
- Option.isSome(cachedConnectedAccounts)
64
- ? cachedConnectedAccounts.value.connectedAccounts
65
- : undefined,
81
+ filterConnectedAccounts(
82
+ Option.isSome(cachedConnectedAccounts)
83
+ ? cachedConnectedAccounts.value.connectedAccounts
84
+ : undefined
85
+ ),
86
options?.connectedAccounts
87
),
88
availableConnectedAccounts: Option.isSome(cachedConnectedAccounts)
@@ -75,7 +95,7 @@ export const createToolRouterSession = (
95
Effect.map(connectionContext => ({
96
...connectionContext,
97
connectedAccounts: mergeConnectedAccounts(
78
- connectionContext.connectedAccounts,
98
+ filterConnectedAccounts(connectionContext.connectedAccounts),
99
options?.connectedAccounts
100
),
101
}))
@@ -102,6 +122,13 @@ export const createToolRouterSession = (
122
auth_configs: connectionContext.authConfigs,
123
connected_accounts: connectionContext.connectedAccounts,
124
manage_connections: { enable: options?.manageConnections ?? false },
125
+ multi_account: options?.multiAccount
126
+ ? {
127
+ enable: options.multiAccount.enable,
128
+ max_accounts_per_toolkit: options.multiAccount.maxAccountsPerToolkit,
129
+ require_explicit_selection: options.multiAccount.requireExplicitSelection,
130
+ }
131
+ : undefined,
132
toolkits:
133
options?.toolkits && options.toolkits.length > 0
134
? { enable: [...options.toolkits] }
ts/packages/cli/test/src/commands/connected-accounts/connected-accounts.link.cmd.test.ts
+31
-10
@@ -80,7 +80,17 @@ const RecordingTerminalUI = TerminalUI.of({
80
});
81
82
describe('CLI: composio dev connected-accounts link', () => {
83
- const aliasPatchSpy = vi.fn();
83
+ const toolRouterCreateSpy = vi.fn(async () => ({
84
+ session_id: 'trs_test_session',
85
+ config: { user_id: 'consumer-user-org_test' },
86
+ mcp: { type: 'http' as const, url: 'https://mcp.test.composio.dev' },
87
+ tool_router_tools: ['COMPOSIO_SEARCH_TOOLS', 'COMPOSIO_MANAGE_CONNECTIONS'],
88
+ }));
89
+ const toolRouterLinkSpy = vi.fn(async () => ({
90
+ connected_account_id: 'con_test_link',
91
+ link_token: 'lt_test_token',
92
+ redirect_url: 'https://app.composio.dev/link?token=lt_test_token',
93
+ }));
94
95
afterEach(() => {
96
vi.clearAllMocks();
@@ -319,20 +329,31 @@ describe('CLI: composio dev connected-accounts link', () => {
329
baseConfigProvider: testConfigProvider,
330
connectedAccountsData: makeConnectedAccountsData({
331
items: [makeConnectedAccount({ status: 'INITIATED' })],
322
- onPatch: params => {
323
- aliasPatchSpy(params);
324
- },
332
}),
333
+ toolRouter: {
334
+ create: toolRouterCreateSpy,
335
+ link: toolRouterLinkSpy,
336
+ },
337
fixture: 'global-test-user-id',
338
})
328
- )('[Given] --alias [Then] it patches the created connected account alias', it => {
329
- it.scoped('updates the connected account alias through the patch API', () =>
339
+ )('[Given] --alias [Then] it passes alias during link creation', it => {
340
+ it.scoped('sends alias to the tool router link API instead of patching afterward', () =>
341
Effect.gen(function* () {
342
yield* cli(['link', 'gmail', '--alias', 'work', '--no-wait']);
332
-
333
- expect(aliasPatchSpy).toHaveBeenCalledWith({
334
- path: '/api/v3/connected_accounts/con_test_link',
335
- body: { alias: 'work' },
343
+ expect(toolRouterCreateSpy).toHaveBeenCalledWith(
344
+ expect.objectContaining({
345
+ connected_accounts: undefined,
346
+ manage_connections: { enable: true },
347
+ multi_account: {
348
+ enable: true,
349
+ max_accounts_per_toolkit: undefined,
350
+ require_explicit_selection: undefined,
351
+ },
352
+ })
353
+ );
354
+ expect(toolRouterLinkSpy).toHaveBeenCalledWith('trs_test_session', {
355
+ toolkit: 'gmail',
356
+ alias: 'work',
357
});
358
})
359
);