Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import { Data, Effect, Option } from 'effect';
import type { Composio } from '@composio/client';
import {
createLocalToolRouterExperimentalPayload,
getAllLocalToolkitSlugs,
} from '@composio/cli-local-tools';
import {
getFreshConsumerToolRouterAuthConfigsFromCache,
getFreshConsumerToolRouterConnectedAccountsFromCache,
writeConsumerConnectedToolkitsCache,
} from 'src/services/consumer-short-term-cache';
import {
resolveToolRouterSessionConnections,
type ToolRouterSessionConnectionContext,
} from 'src/services/tool-router-session-connections';
import { ComposioCliUserConfig } from 'src/services/cli-user-config';
import { CLI_EXPERIMENTAL_FEATURES } from 'src/constants';
import {
ENHANCED_LINK_URL_OVERWRITE,
getConsumerPermissionSnapshot,
type ConsumerPermissionSnapshot,
} from 'src/services/tool-permissions';
export interface CreateToolRouterSessionOptions {
/** Enable auto connection management. Default: false. */
readonly manageConnections?: boolean;
/** Restrict session to these toolkit slugs. */
readonly toolkits?: ReadonlyArray<string>;
/** Consumer-only cache scope for rolling auth-config reuse. */
readonly cacheScope?: {
readonly orgId: string;
readonly projectId: string;
readonly consumerUserId: string;
};
/** Explicit connected-account pins by toolkit slug. */
readonly connectedAccounts?: Record<string, string>;
/** Toolkits whose connected-account pins should be omitted from the session. */
readonly excludeConnectedAccountsForToolkits?: ReadonlyArray<string>;
/** Enable Tool Router multi-account mode for this session. */
readonly multiAccount?: {
readonly enable?: boolean;
readonly maxAccountsPerToolkit?: number;
readonly requireExplicitSelection?: boolean;
};
/** Include bundled local CLI toolkits as Tool Router custom toolkits. Default: true. */
readonly localTools?: {
readonly enable?: boolean;
};
}
export interface CreatedToolRouterSession {
readonly sessionId: string;
/** Inline local-tool custom definitions that should be forwarded to v3.1 search/execute calls. */
readonly localExperimentalPayload?: ReturnType<typeof createLocalToolRouterExperimentalPayload>;
readonly permissionSnapshot?: ConsumerPermissionSnapshot;
readonly connectedAccounts?: Record<string, string>;
readonly connectedAccountWordIds?: Record<string, string>;
}
export class LocalToolRouterDisabledError extends Data.TaggedError(
'effects/LocalToolRouterDisabledError'
)<{
readonly message: string;
readonly requestedToolkits: ReadonlyArray<string>;
}> {}
export class ToolRouterSessionCreateError extends Data.TaggedError(
'effects/ToolRouterSessionCreateError'
)<{
readonly message: string;
readonly cause: unknown;
}> {}
/**
* Create an ephemeral Tool Router session for the given user ID.
* Returns the session id plus any local-tool custom payload bound to the session.
*
* Accepts a pre-resolved client instance (from ComposioClientSingleton)
* so callers can resolve the dependency at layer construction time.
* Used by `ToolsExecutorLive` which already holds the client reference.
*/
export const createToolRouterSessionContext = (
client: Composio,
userId: string,
options?: CreateToolRouterSessionOptions
) =>
Effect.gen(function* () {
const mergeConnectedAccounts = (...mappings: Array<Record<string, string> | undefined>) => {
const merged = Object.assign({}, ...mappings.filter(Boolean));
return Object.keys(merged).length > 0 ? merged : undefined;
};
const requestedToolkits = options?.toolkits ?? [];
const cliConfig = yield* ComposioCliUserConfig;
const localToolsEnabled =
options?.localTools?.enable ??
cliConfig.isExperimentalFeatureEnabled(CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS);
const localToolkitSlugs = new Set(getAllLocalToolkitSlugs());
const requestedLocalToolkits = requestedToolkits.filter(toolkit =>
localToolkitSlugs.has(toolkit.toLowerCase())
);
const remoteToolkits = requestedToolkits.filter(
toolkit => !localToolkitSlugs.has(toolkit.toLowerCase())
);
const shouldIncludeLocalToolkits =
requestedToolkits.length === 0 || requestedLocalToolkits.length > 0;
if (!localToolsEnabled && requestedLocalToolkits.length > 0) {
return yield* Effect.fail(
new LocalToolRouterDisabledError({
message: `Local tools are experimental. Enable them with \`composio config experimental ${CLI_EXPERIMENTAL_FEATURES.LOCAL_TOOLS} on\` before using toolkit filter(s): ${requestedLocalToolkits.join(', ')}.`,
requestedToolkits: requestedLocalToolkits,
})
);
}
const localExperimentalPayload =
!localToolsEnabled || !shouldIncludeLocalToolkits
? undefined
: createLocalToolRouterExperimentalPayload({
toolkits: requestedToolkits.length > 0 ? requestedLocalToolkits : undefined,
});
const excludedToolkits = new Set(
(options?.excludeConnectedAccountsForToolkits ?? []).map(toolkit => toolkit.toLowerCase())
);
const filterConnectedAccounts = (mapping: Record<string, string> | undefined) => {
if (!mapping) return undefined;
const filtered = Object.fromEntries(
Object.entries(mapping).filter(([toolkit]) => !excludedToolkits.has(toolkit.toLowerCase()))
);
return Object.keys(filtered).length > 0 ? filtered : undefined;
};
const resolveConnectedAccountWordIds = (
selected: Record<string, string> | undefined,
available: ToolRouterSessionConnectionContext['availableConnectedAccounts']
) => {
if (!selected || !available) return undefined;
const wordIds = Object.fromEntries(
Object.entries(selected).flatMap(([toolkit, connectedAccountId]) => {
const account = available[toolkit.toLowerCase()]?.find(
item => item.id === connectedAccountId
);
return account?.wordId ? [[toolkit, account.wordId]] : [];
})
);
return Object.keys(wordIds).length > 0 ? wordIds : undefined;
};
const cachedAuthConfigs = options?.cacheScope
? yield* getFreshConsumerToolRouterAuthConfigsFromCache({
orgId: options.cacheScope.orgId,
consumerUserId: options.cacheScope.consumerUserId,
toolkits: remoteToolkits.length > 0 ? remoteToolkits : undefined,
})
: Option.none();
const cachedConnectedAccounts = options?.cacheScope
? yield* getFreshConsumerToolRouterConnectedAccountsFromCache({
orgId: options.cacheScope.orgId,
consumerUserId: options.cacheScope.consumerUserId,
toolkits: remoteToolkits.length > 0 ? remoteToolkits : undefined,
})
: Option.none();
const connectionContext = Option.isSome(cachedAuthConfigs)
? {
connectedToolkits: remoteToolkits,
authConfigs: cachedAuthConfigs.value.authConfigs,
connectedAccounts: mergeConnectedAccounts(
filterConnectedAccounts(
Option.isSome(cachedConnectedAccounts)
? cachedConnectedAccounts.value.connectedAccounts
: undefined
),
options?.connectedAccounts
),
availableConnectedAccounts: Option.isSome(cachedConnectedAccounts)
? cachedConnectedAccounts.value.availableConnectedAccounts
: undefined,
}
: yield* resolveToolRouterSessionConnections(client, userId, {
toolkits: remoteToolkits.length > 0 ? remoteToolkits : undefined,
}).pipe(
Effect.map(connectionContext => ({
...connectionContext,
connectedAccounts: mergeConnectedAccounts(
filterConnectedAccounts(connectionContext.connectedAccounts),
options?.connectedAccounts
),
}))
);
if (options?.cacheScope && Option.isNone(cachedAuthConfigs)) {
yield* writeConsumerConnectedToolkitsCache({
orgId: options.cacheScope.orgId,
consumerUserId: options.cacheScope.consumerUserId,
toolkits: connectionContext.connectedToolkits,
toolRouterAuthConfigs: {
authConfigs: connectionContext.authConfigs,
},
toolRouterConnectedAccounts: {
connectedAccounts: connectionContext.connectedAccounts,
availableConnectedAccounts: connectionContext.availableConnectedAccounts,
},
}).pipe(Effect.catchAll(() => Effect.void));
}
const connectedAccountIds = Object.values(connectionContext.connectedAccounts ?? {}).filter(
(value): value is string => typeof value === 'string'
);
const permissionSnapshot = options?.cacheScope
? yield* getConsumerPermissionSnapshot({
orgId: options.cacheScope.orgId,
projectId: options.cacheScope.projectId,
consumerUserId: options.cacheScope.consumerUserId,
connectedAccountIds,
})
: undefined;
const experimentalPayload = {
...(localExperimentalPayload ?? {}),
...(permissionSnapshot?.enhancedControlsEnabled
? { link_url_overwrite: ENHANCED_LINK_URL_OVERWRITE }
: {}),
};
return yield* Effect.tryPromise({
try: () =>
client.toolRouter.session.create({
user_id: userId,
auth_configs: connectionContext.authConfigs,
connected_accounts: connectionContext.connectedAccounts,
manage_connections: { enable: options?.manageConnections ?? false },
multi_account: options?.multiAccount
? {
enable: options.multiAccount.enable,
max_accounts_per_toolkit: options.multiAccount.maxAccountsPerToolkit,
require_explicit_selection: options.multiAccount.requireExplicitSelection,
}
: undefined,
toolkits: remoteToolkits.length > 0 ? { enable: [...remoteToolkits] } : undefined,
experimental:
Object.keys(experimentalPayload).length > 0 ? experimentalPayload : undefined,
}),
catch: cause =>
new ToolRouterSessionCreateError({
message: 'Failed to create a Tool Router session.',
cause,
}),
}).pipe(
Effect.map((session): CreatedToolRouterSession => ({
sessionId: session.session_id,
localExperimentalPayload,
permissionSnapshot,
connectedAccounts: connectionContext.connectedAccounts,
connectedAccountWordIds: resolveConnectedAccountWordIds(
connectionContext.connectedAccounts,
connectionContext.availableConnectedAccounts
),
}))
);
});
/** Backward-compatible helper for callers that only need the session id. */
export const createToolRouterSession = (
client: Composio,
userId: string,
options?: CreateToolRouterSessionOptions
) =>
createToolRouterSessionContext(client, userId, options).pipe(
Effect.map(session => session.sessionId)
);
/**
* Resolve the Composio client and create a Tool Router session in one step.
* Returns `{ client, sessionId }` — eliminates the 3-step boilerplate
* (resolve singleton, get client, create session) repeated across commands.
*/
export const resolveToolRouterSession = (
client: Composio,
userId: string,
options?: CreateToolRouterSessionOptions
) =>
createToolRouterSessionContext(client, userId, options).pipe(
Effect.map(session => ({ client, ...session }))
);