@devries-cameron20 / composio Mirror · read-only / commits / b53b07a0a
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 06:00 UTC

feat(core): rename custom tools options to localTools and localToolkits (#5215)

## Summary Asked for: stop calling SDK-defined in-process tools "custom tools" and rename the SDK options to **local tools**, in line with the docs rename in #5213. "Custom toolkits" also refers to the unrelated server-side Custom MCP toolkits (`composio.experimental.customToolkits`, `CUSTOM_*` slugs), and the overlap was confusing. These tools already get the `LOCAL_` slug prefix. New names, with the old names kept as deprecated aliases: | New | Deprecated alias (still works) | |---|---| | `experimental.localTools` / `experimental.localToolkits` on `composio.create()` | `experimental.customTools` / `experimental.customToolkits` | | `localTools` / `localToolkits` on `composio.use()` | `customTools` / `customToolkits` | | `session.localTools()` / `session.localToolkits()` | `session.customTools()` / `session.customToolkits()` | | `LocalTool`, `LocalToolkit`, `RegisteredLocalTool`, `RegisteredLocalToolkit`, `CreateLocalToolParams`, `CreateLocalToolkitParams`, `LocalToolExecuteFn` | `Custom*` equivalents | - **Deprecation:** the old names are marked `@deprecated` in JSDoc and keep working. There is no runtime warning, which matches how the package handled the `workbench` → `sandbox` and `toolRouter` → `sessions` renames. - **Passing both names** for the same option throws `ValidationError`, e.g. `Pass either experimental.localTools or experimental.customTools, not both`. - **`sessionConfigId`:** it can't be combined with local tools under either the new or the old names. This is checked at runtime and in the types. - **Request body unchanged:** the API still receives `experimental.custom_tools` / `custom_toolkits`. Tests check that the new and old names produce identical create and attach payloads. - **Not renamed:** internal names (`CustomToolsMap`, `CustomTool.ts`, wire types) and the server-side Custom MCP surface. - **Examples and changeset:** examples in `ts/examples/tool-router` use the new names. The changeset is a minor bump for `@composio/core` and `@composio/slim`, which are version-locked. ## Verification - `pnpm --filter @composio/core typecheck`, including type-tests: passes. A new `type-tests/local-tools.test-d.ts` checks that the old and new type names are interchangeable. - `vitest run` on `customToolRouting`, `toolRouter` and `customTool` tests: 318/318 pass. These cover the new names on create and use, the old names, passing both, the `localTools()` and `customTools()` methods returning the same thing, and `sessionConfigId`. - Full `@composio/core` suite: 1990 pass, 1 fail. The failure is `pinnedDispatcher.node.test.ts`, which also fails without this change because the sandbox runs Node 26 instead of the pinned Node 24. - `pnpm typecheck` in `ts/examples/tool-router`: passes. ## Follow-ups - **Docs:** once this is released, switch the docs code samples to `localTools` / `localToolkits` and remove the "the SDK options keep their names" note added in #5213. - **Python:** #5216 makes the matching `local_tools` / `local_toolkits` change. 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Palash Kala [zen] <palash@composio.dev> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>

composio-zen[bot] committed Nov 4, 2026 at 23:55 UTC b53b07a0adb1c2b8553a0264b5912b52facb667e
19 files changed +496 -138
.changeset/local-tools-rename.md new
+6
@@ -0,0 +1,6 @@
1 +---
2 +'@composio/core': minor
3 +'@composio/slim': minor
4 +---
5 +
6 +Renames in-process custom tools to local tools, so they are no longer confused with the server-side custom toolkits on `composio.experimental.customToolkits`. Pass `experimental.localTools` and `experimental.localToolkits` to `composio.create()`, and `localTools` and `localToolkits` to `composio.use()`. List them with `session.localTools()` and `session.localToolkits()`. The types are now `LocalTool`, `LocalToolkit`, `RegisteredLocalTool`, `RegisteredLocalToolkit`, `CreateLocalToolParams`, `CreateLocalToolkitParams` and `LocalToolExecuteFn`. The `customTools` and `customToolkits` options, the `session.customTools()` and `session.customToolkits()` methods, and the `Custom*` type names are deprecated and keep working. Passing both a new option and its deprecated alias throws `ValidationError`. The request sent to the API is unchanged.
ts/examples/tool-router/src/custom-tools-agent.ts
+5 -5
@@ -162,8 +162,8 @@ const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
162 tools: [setUserRole, updateUserStatus],
163 });
164
165 -const customTools = [getUserDetails, listUserKeys, formatGmailEmail];
166 -const customToolkits = [userManagement];
165 +const localTools = [getUserDetails, listUserKeys, formatGmailEmail];
166 +const localToolkits = [userManagement];
167
168 // ── Agent ─────────────────────────────────────────────────────────
169
@@ -175,13 +175,13 @@ const composio = new Composio({
175
176 const existingSessionId = process.env.COMPOSIO_SESSION_ID;
177 const session = existingSessionId
178 - ? await composio.use(existingSessionId, { customTools, customToolkits })
178 + ? await composio.use(existingSessionId, { localTools, localToolkits })
179 : await composio.create("custom-tools-agent-user", {
180 toolkits: ["weathermap", "gmail"],
181 manageConnections: false,
182 experimental: {
183 - customTools,
184 - customToolkits,
183 + localTools,
184 + localToolkits,
185 },
186 });
187
ts/examples/tool-router/src/custom-tools-e2e.ts
+5 -5
@@ -139,8 +139,8 @@ const userManagement = experimental_createToolkit("USER_MANAGEMENT", {
139 tools: [setUserRole, updateUserStatus],
140 });
141
142 -const customTools = [getUserDetails, listUserKeys, formatGmailEmail];
143 -const customToolkits = [userManagement];
142 +const localTools = [getUserDetails, listUserKeys, formatGmailEmail];
143 +const localToolkits = [userManagement];
144
145 // ────────────────────────────────────────────────────────────────
146 // Run tests
@@ -160,8 +160,8 @@ async function main() {
160 toolkits: ["weathermap", "gmail"],
161 manageConnections: false,
162 experimental: {
163 - customTools,
164 - customToolkits,
163 + localTools,
164 + localToolkits,
165 },
166 });
167 ok(`Session created: ${session.sessionId}`);
@@ -173,7 +173,7 @@ async function main() {
173
174 // ── Existing session reuse with local custom definitions ──
175 try {
176 - const reusedSession = await composio.use(session.sessionId, { customTools, customToolkits });
176 + const reusedSession = await composio.use(session.sessionId, { localTools, localToolkits });
177 const result = await reusedSession.execute("GET_USER_DETAILS", { user_id: "user-1" });
178 if (result.data?.name !== "Alice Johnson") throw new Error(`Unexpected: ${JSON.stringify(result.data)}`);
179 ok("Use: existing session binds custom tools for local execution");
ts/examples/tool-router/src/custom-tools.ts
+2 -2
@@ -94,8 +94,8 @@ const composio = new Composio({
94 const session = await composio.create("default", {
95 toolkits: ["gmail"],
96 experimental: {
97 - customTools: [getUser, createDraft],
98 - customToolkits: [roleManager],
97 + localTools: [getUser, createDraft],
98 + localToolkits: [roleManager],
99 },
100 });
101
ts/examples/tool-router/src/direct-tools-preset.ts
+1 -1
@@ -68,7 +68,7 @@ const session = await composio.create('direct-tools-example-user', {
68 },
69 },
70 experimental: {
71 - customToolkits: [hnResearch],
71 + localToolkits: [hnResearch],
72 },
73 });
74
ts/examples/tool-router/src/preload.ts
+2 -2
@@ -124,8 +124,8 @@ const session = await composio.create('preload-example-user', {
124 },
125 manageConnections: false,
126 experimental: {
127 - customTools: [lookupInternalUser, searchInternalUsers],
128 - customToolkits: [internalAdmin],
127 + localTools: [lookupInternalUser, searchInternalUsers],
128 + localToolkits: [internalAdmin],
129 },
130 });
131
ts/packages/core/src/experimental/index.ts
+6 -1
@@ -19,10 +19,15 @@ export {
19 createCustomToolkit as experimental_createToolkit,
20 } from '../models/CustomTool';
21 export type {
22 + LocalTool,
23 + CreateLocalToolParams,
24 + LocalToolExecuteFn,
25 + SessionContext,
26 + LocalToolkit,
27 + CreateLocalToolkitParams,
28 CustomTool,
29 CreateCustomToolParams,
30 CustomToolExecuteFn,
25 - SessionContext,
31 CustomToolkit,
32 CreateCustomToolkitParams,
33 } from '../types/customTool.types';
ts/packages/core/src/lib/toolRouterParams.ts
+40
@@ -21,6 +21,7 @@ import {
21 ToolRouterProxyExecute,
22 ToolRouterHook,
23 } from '../types/toolRouter.types';
24 +import type { LocalTool, LocalToolkit } from '../types/customTool.types';
25 import { ValidationError } from '../errors';
26 import { z } from 'zod';
27 import type { TypeOf } from 'zod/v3';
@@ -145,6 +146,45 @@ export const resolveToolRouterSandboxConfig = (
146 return config.sandbox ?? config.workbench;
147 };
148
149 +/** Local tools options, accepted under their current names and the deprecated `custom*` aliases. */
150 +export type LocalToolsOptions = {
151 + localTools?: LocalTool[];
152 + localToolkits?: LocalToolkit[];
153 + /** @deprecated Use `localTools` instead. */
154 + customTools?: LocalTool[];
155 + /** @deprecated Use `localToolkits` instead. */
156 + customToolkits?: LocalToolkit[];
157 +};
158 +
159 +/**
160 + * Resolves local tools and toolkits from `localTools` / `localToolkits` or
161 + * their deprecated `customTools` / `customToolkits` aliases. `source` picks
162 + * the option path named in the error: `experimental.*` on create, bare on use.
163 + */
164 +export const resolveLocalToolsOptions = (
165 + options: LocalToolsOptions | undefined,
166 + source: 'create' | 'use'
167 +): { tools?: LocalTool[]; toolkits?: LocalToolkit[] } => {
168 + if (options?.localTools !== undefined && options.customTools !== undefined) {
169 + throw new ValidationError(
170 + source === 'create'
171 + ? 'Pass either experimental.localTools or experimental.customTools, not both. experimental.customTools is a deprecated alias for experimental.localTools.'
172 + : 'Pass either localTools or customTools, not both. customTools is a deprecated alias for localTools.'
173 + );
174 + }
175 + if (options?.localToolkits !== undefined && options.customToolkits !== undefined) {
176 + throw new ValidationError(
177 + source === 'create'
178 + ? 'Pass either experimental.localToolkits or experimental.customToolkits, not both. experimental.customToolkits is a deprecated alias for experimental.localToolkits.'
179 + : 'Pass either localToolkits or customToolkits, not both. customToolkits is a deprecated alias for localToolkits.'
180 + );
181 + }
182 + return {
183 + tools: options?.localTools ?? options?.customTools,
184 + toolkits: options?.localToolkits ?? options?.customToolkits,
185 + };
186 +};
187 +
188 export const transformToolRouterSandboxParams = (
189 params?: ParsedCreateSessionConfig['sandbox'] | ParsedCreateSessionConfig['workbench']
190 ): NonNullable<SessionCreateParams['workbench']> | undefined => {
ts/packages/core/src/models/CustomTool.ts
+25 -30
@@ -24,11 +24,11 @@ import {
24 CreateCustomToolkitBaseSchema,
25 CustomToolSlugSchema,
26 type AnyZodSchema,
27 - type CreateCustomToolParams,
28 - type CreateCustomToolkitParams,
29 - type CustomTool,
30 - type CustomToolkit,
31 - type CustomToolExecuteFn,
27 + type CreateLocalToolParams,
28 + type CreateLocalToolkitParams,
29 + type LocalTool,
30 + type LocalToolkit,
31 + type LocalToolExecuteFn,
32 type CustomToolsMap,
33 type CustomToolsMapEntry,
34 type CustomToolWireDefinition,
@@ -97,10 +97,10 @@ function validateSlugLength(
97 }
98
99 /**
100 - * Create a custom tool for use in tool router sessions.
100 + * Create a local tool for use in tool router sessions.
101 *
102 * The returned object is a lightweight reference containing the tool's metadata
103 - * and execute function. Pass it to `composio.create(userId, { experimental: { customTools: [...] } })`
103 + * and execute function. Pass it to `composio.create(userId, { experimental: { localTools: [...] } })`
104 * to bind it to a session.
105 *
106 * Just return the result data from `execute`, or throw an error.
@@ -113,7 +113,7 @@ function validateSlugLength(
113 *
114 * @param slug - Unique tool identifier (alphanumeric, underscores, hyphens; no LOCAL_ or COMPOSIO_ prefix)
115 * @param options - Tool definition including name, schema, and execute function
116 - * @returns A CustomTool to pass to session creation
116 + * @returns A LocalTool to pass to session creation
117 *
118 * @example Standalone tool (no auth)
119 * ```typescript
@@ -142,8 +142,8 @@ function validateSlugLength(
142 */
143 export function createCustomTool<T extends AnyZodSchema>(
144 slug: string,
145 - options: CreateCustomToolParams<T>
146 -): CustomTool {
145 + options: CreateLocalToolParams<T>
146 +): LocalTool {
147 // Validate slug separately
148 const slugResult = CustomToolSlugSchema.safeParse(slug);
149 if (!slugResult.success) {
@@ -192,12 +192,13 @@ export function createCustomTool<T extends AnyZodSchema>(
192 inputSchema,
193 outputSchema,
194 inputParams,
195 - execute: execute as CustomToolExecuteFn<AnyZodSchema>,
195 + execute: execute as LocalToolExecuteFn<AnyZodSchema>,
196 };
197 }
198
199 /**
200 - * Create a custom toolkit that groups related tools.
200 + * Create a toolkit that groups related local tools. Pass it to
201 + * `composio.create(userId, { experimental: { localToolkits: [...] } })`.
202 *
203 * Tools passed here must NOT have `extendsToolkit` set — they inherit the toolkit identity instead.
204 *
@@ -207,7 +208,7 @@ export function createCustomTool<T extends AnyZodSchema>(
208 *
209 * @param slug - Unique toolkit identifier (alphanumeric, underscores, hyphens; no LOCAL_ or COMPOSIO_ prefix)
210 * @param options - Toolkit definition including name, description, and tools
210 - * @returns A CustomToolkit to pass to session creation
211 + * @returns A LocalToolkit to pass to session creation
212 *
213 * @example
214 * ```typescript
@@ -218,10 +219,7 @@ export function createCustomTool<T extends AnyZodSchema>(
219 * });
220 * ```
221 */
221 -export function createCustomToolkit(
222 - slug: string,
223 - options: CreateCustomToolkitParams
224 -): CustomToolkit {
222 +export function createCustomToolkit(slug: string, options: CreateLocalToolkitParams): LocalToolkit {
223 // Validate slug
224 const slugResult = CustomToolSlugSchema.safeParse(slug);
225 if (!slugResult.success) {
@@ -322,16 +320,13 @@ const addOriginalSlugAlias = (params: {
320 * @returns Maps for O(1) lookup by both final and original slug
321 * @throws If duplicate slugs or cross-group collisions
322 */
325 -export function buildCustomToolsMap(
326 - tools: CustomTool[],
327 - toolkits?: CustomToolkit[]
328 -): CustomToolsMap {
323 +export function buildCustomToolsMap(tools: LocalTool[], toolkits?: LocalToolkit[]): CustomToolsMap {
324 const byFinalSlug = new Map<string, CustomToolsMapEntry>();
325 const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
326 const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
327 const ambiguousOriginalSlugs = new Set<string>();
328
334 - const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
329 + const addEntry = (handle: LocalTool, finalSlug: string, toolkit?: string) => {
330 const originalSlug = handle.slug.toUpperCase();
331 // Custom tool slugs are matched case-insensitively across local and response maps.
332 const finalSlugKey = finalSlug.toUpperCase();
@@ -426,7 +421,7 @@ function preloadWireProperty(
421 }
422
423 export function serializeCustomTools(
429 - tools: CustomTool[],
424 + tools: LocalTool[],
425 options: CustomToolSerializationOptions = {}
426 ): CustomToolWireDefinition[] {
427 const defaultPreload = options.defaultPreload ?? false;
@@ -449,7 +444,7 @@ export function serializeCustomTools(
444 * @returns Array of CustomToolkitDefinition for the API payload
445 */
446 export function serializeCustomToolkits(
452 - toolkits: CustomToolkit[],
447 + toolkits: LocalToolkit[],
448 options: CustomToolSerializationOptions = {}
449 ): CustomToolkitWireDefinition[] {
450 const defaultPreload = options.defaultPreload ?? false;
@@ -480,8 +475,8 @@ export function serializeCustomToolkits(
475 * @returns Maps for O(1) lookup by both final and original slug
476 */
477 export function buildCustomToolsMapFromResponse(
483 - tools: CustomTool[],
484 - toolkits: CustomToolkit[] | undefined,
478 + tools: LocalTool[],
479 + toolkits: LocalToolkit[] | undefined,
480 experimental:
481 SessionCreateResponse['experimental'] | SessionRetrieveResponse['experimental'] | undefined
482 ): CustomToolsMap {
@@ -490,11 +485,11 @@ export function buildCustomToolsMapFromResponse(
485 const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
486 const ambiguousOriginalSlugs = new Set<string>();
487
493 - type HandleMatch = { handle: CustomTool; toolkit?: string };
488 + type HandleMatch = { handle: LocalTool; toolkit?: string };
489 const handlesByQualifiedOriginalSlug = new Map<string, HandleMatch>();
490 const handlesByOriginalSlug = new Map<string, HandleMatch[]>();
491
497 - const registerHandle = (handle: CustomTool, toolkit?: string) => {
492 + const registerHandle = (handle: LocalTool, toolkit?: string) => {
493 const originalSlug = handle.slug.toUpperCase();
494 const match = { handle, toolkit };
495 handlesByQualifiedOriginalSlug.set(qualifiedOriginalSlugKey(toolkit, originalSlug), match);
@@ -636,8 +631,8 @@ export function findCustomToolMapEntryByToolkitAndOriginalSlug(
631 /**
632 * Reject legacy attempts to preload custom tools through top-level preload.tools.
633 *
639 - * Custom tool direct exposure is controlled by CustomTool.preload /
640 - * CustomToolkit.preload so it follows the current SDK-provided custom
634 + * Custom tool direct exposure is controlled by LocalTool.preload /
635 + * LocalToolkit.preload so it follows the current SDK-provided custom
636 * definitions instead of stale session config.
637 *
638 * @internal
ts/packages/core/src/models/ToolRouter.ts
+24 -14
@@ -39,8 +39,8 @@ import {
39 SessionRetrieveResponse,
40 } from '@composio/client/resources/tool-router/session';
41 import type {
42 - CustomTool,
43 - CustomToolkit,
42 + LocalTool,
43 + LocalToolkit,
44 InlineCustomToolsWirePayload,
45 } from '../types/customTool.types';
46 import {
@@ -54,6 +54,8 @@ import {
54 transformToolRouterProxyExecuteParams,
55 transformToolRouterHooksParams,
56 resolveToolRouterSandboxConfig,
57 + resolveLocalToolsOptions,
58 + type LocalToolsOptions,
59 } from '../lib/toolRouterParams';
60 import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
61 import { buildMCPServerConfig } from '../lib/toolRouterMcp';
@@ -91,8 +93,8 @@ function preloadsAllCustomTools(preload?: { tools?: readonly string[] | string }
93 }
94
95 function prepareInlineCustomTools(options: {
94 - customTools?: CustomTool[];
95 - customToolkits?: CustomToolkit[];
96 + customTools?: LocalTool[];
97 + customToolkits?: LocalToolkit[];
98 defaultPreload?: boolean;
99 preloadTools?: readonly string[] | typeof PRELOAD_TOOLS_ALL;
100 }): InlineCustomToolsWirePayload | undefined {
@@ -181,6 +183,7 @@ export class ToolRouter<
183 * @param config {ToolRouterCreateSessionConfig} The config for the tool router session
184 * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
185 * @throws {ComposioMCPDestinationError} When `mcp: true` is passed and the MCP URL is not on the API origin
186 + * @throws {ValidationError} When a local tools option and its deprecated `custom*` alias are both passed
187 *
188 * @example
189 * ```typescript
@@ -192,8 +195,8 @@ export class ToolRouter<
195 * toolkits: ['gmail'],
196 * manageConnections: true,
197 * experimental: {
195 - * customTools: [myCustomTool],
196 - * customToolkits: [myToolkit],
198 + * localTools: [myLocalTool],
199 + * localToolkits: [myLocalToolkit],
200 * },
201 * });
202 *
@@ -225,9 +228,10 @@ export class ToolRouter<
228 const routerConfig = parseSessionConfigInput(ToolRouterCreateSessionConfigSchema, config ?? {});
229 const isDirectToolsPreset = routerConfig.sessionPreset === SessionPreset.DIRECT_TOOLS;
230
228 - // Extract custom tools/toolkits from experimental config
229 - const customTools = routerConfig.experimental?.customTools;
230 - const customToolkits = routerConfig.experimental?.customToolkits;
231 + const { tools: customTools, toolkits: customToolkits } = resolveLocalToolsOptions(
232 + routerConfig.experimental,
233 + 'create'
234 + );
235 const defaultCustomPreload = preloadsAllCustomTools(routerConfig.preload);
236 const inlineCustomToolsPayload = prepareInlineCustomTools({
237 customTools,
@@ -351,8 +355,12 @@ export class ToolRouter<
355 * origins is logged, so native tools keep working.
356 *
357 * @param id {string} The id of the session to use
358 + * @param options {object} Optional session reuse options
359 + * @param options.localTools Local tools to attach to the session; `customTools` is a deprecated alias.
360 + * @param options.localToolkits Toolkits of local tools to attach; `customToolkits` is a deprecated alias.
361 * @returns {Promise<Session<TToolCollection, TTool, TProvider>>} The tool router session
362 * @throws {ComposioMCPDestinationError} When `mcp: true` is passed and the MCP URL is not on the API origin
363 + * @throws {ValidationError} When a local tools option and its deprecated `custom*` alias are both passed
364 *
365 * @example
366 * ```typescript
@@ -370,21 +378,23 @@ export class ToolRouter<
378 // in the returned type. See https://docs.composio.dev/docs/sessions-via-mcp
379 async use(
380 id: string,
373 - options: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp: true },
381 + options: LocalToolsOptions & { mcp: true },
382 requestOptions?: ComposioRequestOptions
383 ): Promise<Session<TToolCollection, TTool, TProvider>>;
384 async use(
385 id: string,
378 - options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean },
386 + options?: LocalToolsOptions & { mcp?: boolean },
387 requestOptions?: ComposioRequestOptions
388 ): Promise<SessionWithoutMcp<TToolCollection, TTool, TProvider>>;
389 async use(
390 id: string,
383 - options?: { customTools?: CustomTool[]; customToolkits?: CustomToolkit[]; mcp?: boolean },
391 + options?: LocalToolsOptions & { mcp?: boolean },
392 requestOptions?: ComposioRequestOptions
393 ): Promise<Session<TToolCollection, TTool, TProvider>> {
386 - const customTools = options?.customTools;
387 - const customToolkits = options?.customToolkits;
394 + const { tools: customTools, toolkits: customToolkits } = resolveLocalToolsOptions(
395 + options,
396 + 'use'
397 + );
398 const hasCustoms = !!(customTools?.length || customToolkits?.length);
399
400 let session: SessionRetrieveResponse | SessionAttachResponse;
ts/packages/core/src/models/ToolRouterSession.ts
+22 -8
@@ -67,8 +67,8 @@ import type {
67 CustomToolsMap,
68 CustomToolsMapEntry,
69 SessionContext,
70 - RegisteredCustomTool,
71 - RegisteredCustomToolkit,
70 + RegisteredLocalTool,
71 + RegisteredLocalToolkit,
72 } from '../types/customTool.types';
73 import { ToolSchema, type Tool, type ToolExecuteResponse } from '../types/tool.types';
74 import type { SessionProxyExecuteParams } from '../types/toolRouter.types';
@@ -384,13 +384,13 @@ export class ToolRouterSession<
384 }
385
386 /**
387 - * List all custom tools registered in this session.
387 + * List all local tools registered in this session.
388 * Returns tools with their final slugs, schemas, and resolved toolkit.
389 *
390 * @param options.toolkit - Filter by toolkit slug (e.g. 'gmail', 'DEV_TOOLS')
391 - * @returns Array of registered custom tools
391 + * @returns Array of registered local tools
392 */
393 - customTools(options?: { toolkit?: string }): RegisteredCustomTool[] {
393 + localTools(options?: { toolkit?: string }): RegisteredLocalTool[] {
394 if (!this.customToolsMap) return [];
395
396 const entries = Array.from(this.customToolsMap.byFinalSlug.values());
@@ -409,12 +409,19 @@ export class ToolRouterSession<
409 }
410
411 /**
412 - * List all custom toolkits registered in this session.
412 + * @deprecated Use `localTools()` instead.
413 + */
414 + customTools(options?: { toolkit?: string }): RegisteredLocalTool[] {
415 + return this.localTools(options);
416 + }
417 +
418 + /**
419 + * List all toolkits of local tools registered in this session.
420 * Returns toolkits with their tools showing final slugs.
421 *
415 - * @returns Array of registered custom toolkits
422 + * @returns Array of registered toolkits of local tools
423 */
417 - customToolkits(): RegisteredCustomToolkit[] {
424 + localToolkits(): RegisteredLocalToolkit[] {
425 const toolkits = this.customToolsMap?.toolkits;
426 if (!toolkits?.length) return [];
427
@@ -444,6 +451,13 @@ export class ToolRouterSession<
451 }));
452 }
453
454 + /**
455 + * @deprecated Use `localToolkits()` instead.
456 + */
457 + customToolkits(): RegisteredLocalToolkit[] {
458 + return this.localToolkits();
459 + }
460 +
461 /**
462 * Initiate an authorization flow for a toolkit.
463 * Returns a ConnectionRequest with a redirect URL for the user.
ts/packages/core/src/models/Tools.ts
+4 -4
@@ -409,9 +409,9 @@ export class Tools<
409 * Lists Composio API tools available to the SDK.
410 *
411 * This method fetches remote Composio tools from the API in raw format. The response can be
412 - * filtered and modified as needed. Local experimental custom tools are session-scoped; attach
412 + * filtered and modified as needed. Experimental local tools are session-scoped; attach
413 * them when creating or reusing a Tool Router session, then use `session.tools()`,
414 - * `session.customTools()`, or `session.execute()`.
414 + * `session.localTools()`, or `session.execute()`.
415 * It provides access to the underlying tool data without provider-specific wrapping.
416 *
417 * @param {ToolListParams} query - Query parameters to filter the tools (required)
@@ -628,8 +628,8 @@ export class Tools<
628 * This method fetches a single tool in raw format without provider-specific wrapping,
629 * providing direct access to the tool's schema and metadata. Tool versions are controlled
630 * at the Composio SDK initialization level through the `toolkitVersions` configuration.
631 - * Local experimental custom tools are session-scoped; attach them when creating or reusing a
632 - * Tool Router session, then use `session.tools()`, `session.customTools()`, or
631 + * Experimental local tools are session-scoped; attach them when creating or reusing a
632 + * Tool Router session, then use `session.tools()`, `session.localTools()`, or
633 * `session.execute()`.
634 *
635 * @param {string} slug - The unique identifier of the tool (e.g., 'GITHUB_GET_REPOS')
ts/packages/core/src/types/customTool.types.ts
+49 -28
@@ -46,18 +46,21 @@ export interface SessionContext {
46 }
47
48 /**
49 - * Execute function for custom tools.
49 + * Execute function for local tools.
50 * Just return the result data, or throw an error. The SDK wraps it internally.
51 *
52 * Supports two call patterns:
53 * - `(input) => data` — for tools that don't need session context
54 * - `(input, ctx) => data` — for tools that need to call other tools or proxy APIs
55 */
56 -export type CustomToolExecuteFn<T extends AnyZodSchema> = (
56 +export type LocalToolExecuteFn<T extends AnyZodSchema> = (
57 input: InferZodSchema<T>,
58 ctx: SessionContext
59 ) => Promise<Record<string, unknown>>;
60
61 +/** @deprecated Use `LocalToolExecuteFn` instead; local tools were previously called custom tools. */
62 +export type CustomToolExecuteFn<T extends AnyZodSchema> = LocalToolExecuteFn<T>;
63 +
64 /**
65 * Zod schema for validating a custom tool slug.
66 * Alphanumeric, underscores, and hyphens only. No `LOCAL_` or `COMPOSIO_` prefix.
@@ -101,8 +104,8 @@ export const CreateCustomToolBaseSchema = z.object({
104 ),
105 });
106
104 -/** Options for creating a custom tool via `createCustomTool()`. */
105 -export type CreateCustomToolParams<T extends AnyZodSchema> = z.infer<
107 +/** Options for creating local tools via `experimental_createTool()`. */
108 +export type CreateLocalToolParams<T extends AnyZodSchema> = z.infer<
109 typeof CreateCustomToolBaseSchema
110 > & {
111 /** Zod schema for input parameters */
@@ -110,14 +113,17 @@ export type CreateCustomToolParams<T extends AnyZodSchema> = z.infer<
113 /** Optional Zod schema for output parameters (sent to backend for documentation) */
114 outputParams?: AnyZodSchema;
115 /** The function that executes the tool */
113 - execute: CustomToolExecuteFn<T>;
116 + execute: LocalToolExecuteFn<T>;
117 };
118
119 +/** @deprecated Use `CreateLocalToolParams` instead; local tools were previously called custom tools. */
120 +export type CreateCustomToolParams<T extends AnyZodSchema> = CreateLocalToolParams<T>;
121 +
122 /**
117 - * Custom tool definition returned from `createCustomTool()`.
118 - * Pass to `composio.create(userId, { experimental: { customTools: [...] } })` to bind to a session.
123 + * One of your local tools, returned from `experimental_createTool()`; it runs in your process.
124 + * Pass to `composio.create(userId, { experimental: { localTools: [...] } })` to bind to a session.
125 */
120 -export interface CustomTool {
126 +export interface LocalTool {
127 readonly slug: string;
128 readonly name: string;
129 readonly description: string;
@@ -138,9 +144,12 @@ export interface CustomTool {
144 /** @internal Original Zod schema — used for runtime input validation (defaults, coercions, transforms) */
145 readonly inputParams: AnyZodSchema;
146 /** Direct reference to the execute function — useful for testing */
141 - readonly execute: CustomToolExecuteFn<AnyZodSchema>;
147 + readonly execute: LocalToolExecuteFn<AnyZodSchema>;
148 }
149
150 +/** @deprecated Use `LocalTool` instead; local tools were previously called custom tools. */
151 +export type CustomTool = LocalTool;
152 +
153 /** Serialized tool definition sent to backend for search indexing. Uses official client type. */
154 export type CustomToolDefinition = NonNullable<
155 NonNullable<SessionCreateParams['experimental']>['custom_tools']
@@ -167,17 +176,20 @@ export const CreateCustomToolkitBaseSchema = z.object({
176 ),
177 });
178
170 -/** Options for creating a custom toolkit via `createCustomToolkit()`. */
171 -export type CreateCustomToolkitParams = z.infer<typeof CreateCustomToolkitBaseSchema> & {
179 +/** Options for grouping local tools into a toolkit via `experimental_createToolkit()`. */
180 +export type CreateLocalToolkitParams = z.infer<typeof CreateCustomToolkitBaseSchema> & {
181 /** Tools to include in this toolkit. Must not have `extendsToolkit` set. */
173 - tools: CustomTool[];
182 + tools: LocalTool[];
183 };
184
185 +/** @deprecated Use `CreateLocalToolkitParams` instead; local toolkits were previously called custom toolkits. */
186 +export type CreateCustomToolkitParams = CreateLocalToolkitParams;
187 +
188 /**
177 - * Custom toolkit definition returned from `createCustomToolkit()`.
178 - * Pass to `composio.create(userId, { experimental: { customToolkits: [...] } })`.
189 + * A toolkit of local tools returned from `experimental_createToolkit()`.
190 + * Pass to `composio.create(userId, { experimental: { localToolkits: [...] } })`.
191 */
180 -export interface CustomToolkit {
192 +export interface LocalToolkit {
193 readonly slug: string;
194 readonly name: string;
195 readonly description: string;
@@ -186,9 +198,12 @@ export interface CustomToolkit {
198 * Tool-level preload values override this default.
199 */
200 readonly preload?: boolean;
189 - readonly tools: readonly CustomTool[];
201 + readonly tools: readonly LocalTool[];
202 }
203
204 +/** @deprecated Use `LocalToolkit` instead; local toolkits were previously called custom toolkits. */
205 +export type CustomToolkit = LocalToolkit;
206 +
207 /** Serialized toolkit definition sent to backend. Uses official client type. */
208 export type CustomToolkitDefinition = NonNullable<
209 NonNullable<NonNullable<SessionCreateParams['experimental']>['custom_toolkits']>[number]
@@ -207,7 +222,7 @@ export interface InlineCustomToolsWirePayload {
222
223 /** @internal Entry in the per-session custom tools routing map. */
224 export type CustomToolsMapEntry = {
210 - handle: CustomTool;
225 + handle: LocalTool;
226 /** @internal The final slug assigned by the prefixing rules (e.g. LOCAL_GREP, LOCAL_GMAIL_GET_EMAILS) */
227 finalSlug: string;
228 /** Resolved toolkit — from extendsToolkit, parent custom toolkit, or undefined for standalone */
@@ -224,36 +239,42 @@ export type CustomToolsMap = {
239 byToolkitAndOriginalSlug?: Map<string, CustomToolsMapEntry>;
240 /** Original slugs that appear in multiple toolkits and cannot be resolved safely without the final slug */
241 ambiguousOriginalSlugs?: Set<string>;
227 - /** The original custom toolkits passed at session creation — used for session.customToolkits() */
228 - toolkits?: CustomToolkit[];
229 - /** The original standalone custom tools passed at session creation — kept for inline re-injection on later requests. */
230 - tools?: CustomTool[];
242 + /** The original local toolkits passed at session creation — used for session.localToolkits() */
243 + toolkits?: LocalToolkit[];
244 + /** The original standalone local tools passed at session creation — kept for inline re-injection on later requests. */
245 + tools?: LocalTool[];
246 };
247
248 // ────────────────────────────────────────────────────────────────
234 -// Registered custom tool types (returned by session.customTools())
249 +// Registered local tool types (returned by session.localTools())
250 // ────────────────────────────────────────────────────────────────
251
237 -/** A custom tool as registered in a session, with its final resolved slug. */
238 -export interface RegisteredCustomTool {
252 +/** One of your local tools as registered in a session, with its final resolved slug. */
253 +export interface RegisteredLocalTool {
254 /** The final slug as registered with the backend (e.g. LOCAL_GREP, LOCAL_GMAIL_GET_EMAILS) */
255 slug: string;
256 name: string;
257 description: string;
243 - /** Resolved toolkit — extendsToolkit value, custom toolkit slug, or undefined for standalone */
258 + /** Resolved toolkit — extendsToolkit value, local toolkit slug, or undefined for standalone */
259 toolkit?: string;
260 inputSchema: Record<string, unknown>;
261 outputSchema?: Record<string, unknown>;
262 }
263
249 -/** A custom toolkit as registered in a session, with final slugs on nested tools. */
250 -export interface RegisteredCustomToolkit {
264 +/** A toolkit of local tools as registered in a session, with final slugs on nested tools. */
265 +export interface RegisteredLocalToolkit {
266 slug: string;
267 name: string;
268 description: string;
254 - tools: RegisteredCustomTool[];
269 + tools: RegisteredLocalTool[];
270 }
271
272 +/** @deprecated Use `RegisteredLocalTool` instead; local tools were previously called custom tools. */
273 +export type RegisteredCustomTool = RegisteredLocalTool;
274 +
275 +/** @deprecated Use `RegisteredLocalToolkit` instead; local toolkits were previously called custom toolkits. */
276 +export type RegisteredCustomToolkit = RegisteredLocalToolkit;
277 +
278 // ────────────────────────────────────────────────────────────────
279 // Response types from the backend (slug + original_slug mapping)
280 // ────────────────────────────────────────────────────────────────
ts/packages/core/src/types/toolRouter.types.ts
+39 -17
@@ -13,11 +13,11 @@ import type {
13 SessionExecuteParams,
14 } from '@composio/client/resources/tool-router/session';
15 import type {
16 - CustomTool,
17 - CustomToolkit,
16 + LocalTool,
17 + LocalToolkit,
18 InlineCustomToolsWirePayload,
19 - RegisteredCustomTool,
20 - RegisteredCustomToolkit,
19 + RegisteredLocalTool,
20 + RegisteredLocalToolkit,
21 } from './customTool.types';
22 import { PRELOAD_TOOLS_ALL } from '../lib/toolRouterConstants';
23 import { addSessionConfigConflictIssue } from '../lib/sessionConfigConflict';
@@ -517,24 +517,34 @@ const ToolRouterCreateSessionConfigBaseSchema = z
517 })
518 .optional()
519 .describe('Configuration for assistive prompt generation'),
520 - customTools: z
521 - .array(z.custom<CustomTool>())
520 + localTools: z
521 + .array(z.custom<LocalTool>())
522 .optional()
523 .describe(
524 - 'Custom tools to include in this session. Created via createCustomTool() from @composio/core/experimental.'
524 + 'Local tools to include in this session. They run in your process. Created via experimental_createTool() from @composio/core.'
525 ),
526 - customToolkits: z
527 - .array(z.custom<CustomToolkit>())
526 + localToolkits: z
527 + .array(z.custom<LocalToolkit>())
528 .optional()
529 .describe(
530 - 'Custom toolkits to include in this session. Created via createCustomToolkit() from @composio/core/experimental.'
530 + 'Toolkits of local tools to include in this session. Created via experimental_createToolkit() from @composio/core.'
531 ),
532 + /** @deprecated Use `localTools` instead. */
533 + customTools: z
534 + .array(z.custom<LocalTool>())
535 + .optional()
536 + .describe('Deprecated alias for localTools. Accepted for backwards compatibility.'),
537 + /** @deprecated Use `localToolkits` instead. */
538 + customToolkits: z
539 + .array(z.custom<LocalToolkit>())
540 + .optional()
541 + .describe('Deprecated alias for localToolkits. Accepted for backwards compatibility.'),
542 sessionConfigId: z
543 .string()
544 .min(1)
545 .optional()
546 .describe(
537 - 'ID of a saved Session config (`sc_…`) to apply when the session is created. Cannot be combined with toolkits, tools, tags, customTools or customToolkits.'
547 + 'ID of a saved Session config (`sc_…`) to apply when the session is created. Cannot be combined with toolkits, tools, tags, localTools or localToolkits.'
548 ),
549 /**
550 * What happens to a call that needs the user's approval when the
@@ -558,6 +568,8 @@ const ToolRouterCreateSessionConfigBaseSchema = z
568 config.tools !== undefined && 'tools',
569 config.tags !== undefined && 'tags',
570 config.hooks !== undefined && 'hooks',
571 + config.experimental.localTools !== undefined && 'experimental.localTools',
572 + config.experimental.localToolkits !== undefined && 'experimental.localToolkits',
573 config.experimental.customTools !== undefined && 'experimental.customTools',
574 config.experimental.customToolkits !== undefined && 'experimental.customToolkits',
575 ].filter((field): field is string => field !== false)
@@ -626,7 +638,11 @@ export const ToolRouterCreateSessionConfigSchema = z
638 * @param {object} [preload] - Tools to preload into session.tools() and the MCP tool list
639 * @param {string[] | 'all'} [preload.tools] - Tool slugs to preload, or "all" to preload every app tool allowed by the session filters. "all" requires a positive filter such as toolkits, tools, or tags; the backend validates and caps the final tool set.
640 * @param {object} [experimental] - Experimental features configuration. Not stable; may change or be removed.
629 - * @param {string} [experimental.sessionConfigId] - ID of a saved Session config (`sc_…`) to apply at creation; see `composio.sessionConfigs`. Cannot be combined with `toolkits`, `tools`, `tags`, `hooks`, `experimental.customTools` or `experimental.customToolkits`. Per-session fields such as `authConfigs`, `connectedAccounts`, `manageConnections`, `sandbox`, `multiAccount` and `preload` stay allowed.
641 + * @param {LocalTool[]} [experimental.localTools] - Local tools to include in this session, created with `experimental_createTool()`. They run in your process.
642 + * @param {LocalToolkit[]} [experimental.localToolkits] - Toolkits of local tools to include in this session, created with `experimental_createToolkit()`.
643 + * @param {LocalTool[]} [experimental.customTools] - Deprecated alias for `experimental.localTools`.
644 + * @param {LocalToolkit[]} [experimental.customToolkits] - Deprecated alias for `experimental.localToolkits`.
645 + * @param {string} [experimental.sessionConfigId] - ID of a saved Session config (`sc_…`) to apply at creation; see `composio.sessionConfigs`. Cannot be combined with `toolkits`, `tools`, `tags`, `hooks`, `experimental.localTools` or `experimental.localToolkits` (or their deprecated aliases `experimental.customTools` / `experimental.customToolkits`). Per-session fields such as `authConfigs`, `connectedAccounts`, `manageConnections`, `sandbox`, `multiAccount` and `preload` stay allowed.
646 */
647 export type ToolRouterCreateSessionConfig =
648 InlineAccessCreateSessionConfig | SavedConfigCreateSessionConfig;
@@ -652,9 +668,11 @@ type SavedConfigCreateSessionConfig = Omit<
668 hooks?: never;
669 experimental: Omit<
670 ParsedCreateSessionExperimental,
655 - 'sessionConfigId' | 'customTools' | 'customToolkits'
671 + 'sessionConfigId' | 'localTools' | 'localToolkits' | 'customTools' | 'customToolkits'
672 > & {
673 sessionConfigId: string;
674 + localTools?: never;
675 + localToolkits?: never;
676 customTools?: never;
677 customToolkits?: never;
678 };
@@ -1468,10 +1486,14 @@ export interface Session<
1486 listConfigHistory: ToolRouterSessionListConfigHistoryFn;
1487 /** Proxy an API call through Composio's auth layer using the session's connected account */
1488 proxyExecute: ToolRouterSessionProxyExecuteFn;
1471 - /** List custom tools registered in this session, with their final slugs and schemas */
1472 - customTools: (options?: { toolkit?: string }) => RegisteredCustomTool[];
1473 - /** List custom toolkits registered in this session, with final slugs on nested tools */
1474 - customToolkits: () => RegisteredCustomToolkit[];
1489 + /** List local tools registered in this session, with their final slugs and schemas */
1490 + localTools: (options?: { toolkit?: string }) => RegisteredLocalTool[];
1491 + /** List toolkits of local tools registered in this session, with final slugs on nested tools */
1492 + localToolkits: () => RegisteredLocalToolkit[];
1493 + /** @deprecated Use `localTools()` instead. */
1494 + customTools: (options?: { toolkit?: string }) => RegisteredLocalTool[];
1495 + /** @deprecated Use `localToolkits()` instead. */
1496 + customToolkits: () => RegisteredLocalToolkit[];
1497 /** Experimental features (files, assistive prompt, etc.) */
1498 experimental: SessionExperimental;
1499 }
ts/packages/core/test/models/customToolRouting.test.ts
+121 -12
@@ -2,8 +2,12 @@ import { describe, it, expect, vi, beforeEach, assert } from 'vitest';
2 import { z } from 'zod/v3';
3 import { ToolRouter } from '../../src/models/ToolRouter';
4 import { ToolRouterSession } from '../../src/models/ToolRouterSession';
5 -import { createCustomTool, buildCustomToolsMap } from '../../src/models/CustomTool';
6 -import { ComposioToolInputRequiredError } from '../../src/errors';
5 +import {
6 + createCustomTool,
7 + createCustomToolkit,
8 + buildCustomToolsMap,
9 +} from '../../src/models/CustomTool';
10 +import { ComposioToolInputRequiredError, ValidationError } from '../../src/errors';
11 import { MockProvider } from '../utils/mocks/provider.mock';
12 import ComposioClient from '@composio/client';
13 import type { CustomTool, SessionContext } from '../../src/types/customTool.types';
@@ -86,21 +90,23 @@ beforeEach(() => {
90
91 // ── Fixtures ─────────────────────────────────────────────────────
92
93 +const sessionCreateResponse = {
94 + session_id: 'sess_123',
95 + config: {
96 + preload: { tools: [] },
97 + user_id: 'user_1',
98 + },
99 + config_version: 1,
100 + mcp: { type: 'http', url: 'https://api.composio.dev/api/v3/tool_router/session/sess_123' },
101 + tool_router_tools: [],
102 +};
103 +
104 const createMockClient = () => ({
105 baseURL: 'https://api.composio.dev',
106 apiKey: 'test-api-key',
107 toolRouter: {
108 session: {
94 - create: vi.fn().mockResolvedValue({
95 - session_id: 'sess_123',
96 - config: {
97 - preload: { tools: [] },
98 - user_id: 'user_1',
99 - },
100 - config_version: 1,
101 - mcp: { type: 'http', url: 'https://api.composio.dev/api/v3/tool_router/session/sess_123' },
102 - tool_router_tools: [],
103 - }),
109 + create: vi.fn().mockResolvedValue(sessionCreateResponse),
110 retrieve: vi.fn(),
111 link: vi.fn(),
112 toolkits: vi.fn(),
@@ -283,6 +289,109 @@ describe('ToolRouter.create() with customTools', () => {
289 });
290 });
291
292 +describe('ToolRouter.create() with localTools', () => {
293 + let mockClient: ReturnType<typeof createMockClient>;
294 + let router: ToolRouter<unknown, unknown, MockProvider>;
295 +
296 + const devToolkit = createCustomToolkit('DEV_TOOLS', {
297 + name: 'Dev Tools',
298 + description: 'Local dev utilities',
299 + tools: [
300 + createCustomTool('GREP', {
301 + name: 'Grep',
302 + description: 'Search local text',
303 + inputParams: z.object({ pattern: z.string() }),
304 + execute: async () => ({ matches: [] }),
305 + }),
306 + ],
307 + });
308 +
309 + beforeEach(() => {
310 + vi.clearAllMocks();
311 + mockClient = createMockClient();
312 + mockClient.toolRouter.session.create.mockResolvedValue({
313 + ...sessionCreateResponse,
314 + experimental: {
315 + custom_tools: [{ slug: 'LOCAL_GET_USER_CONTEXT', original_slug: 'GET_USER_CONTEXT' }],
316 + custom_toolkits: [
317 + { slug: 'DEV_TOOLS', tools: [{ slug: 'LOCAL_DEV_TOOLS_GREP', original_slug: 'GREP' }] },
318 + ],
319 + },
320 + });
321 + router = new ToolRouter(mockClient as unknown as ComposioClient, {
322 + apiKey: 'test-key',
323 + provider: new MockProvider(),
324 + });
325 + });
326 +
327 + it('sends the same custom_tools/custom_toolkits wire payload as the deprecated names', async () => {
328 + await router.create('user_1', {
329 + experimental: { localTools: [customToolHandle], localToolkits: [devToolkit] },
330 + });
331 + await router.create('user_1', {
332 + experimental: { customTools: [customToolHandle], customToolkits: [devToolkit] },
333 + });
334 +
335 + const [[localPayload], [customPayload]] = mockClient.toolRouter.session.create.mock.calls;
336 + expect(localPayload.experimental).toEqual({
337 + custom_tools: [expect.objectContaining({ slug: 'GET_USER_CONTEXT' })],
338 + custom_toolkits: [expect.objectContaining({ slug: 'DEV_TOOLS' })],
339 + });
340 + expect(customPayload).toEqual(localPayload);
341 + });
342 +
343 + it('routes local tools passed via localTools in-process', async () => {
344 + const session = await router.create('user_1', {
345 + experimental: { localTools: [customToolHandle] },
346 + });
347 +
348 + const result = await session.execute('GET_USER_CONTEXT', { category: 'all' });
349 +
350 + expect(result.error).toBeNull();
351 + expect(localExecute).toHaveBeenCalled();
352 + expect(mockClient.toolRouter.session.execute).not.toHaveBeenCalled();
353 + });
354 +
355 + it.each([
356 + [
357 + 'experimental.localTools or experimental.customTools',
358 + { localTools: [customToolHandle], customTools: [customToolHandle] },
359 + ],
360 + [
361 + 'experimental.localToolkits or experimental.customToolkits',
362 + { localToolkits: [devToolkit], customToolkits: [] },
363 + ],
364 + ])('rejects passing both %s without calling the API', async (fields, experimental) => {
365 + const error = await router.create('user_1', { experimental }).catch(e => e);
366 +
367 + expect(error).toBeInstanceOf(ValidationError);
368 + expect(error.message).toContain(`Pass either ${fields}, not both`);
369 + expect(mockClient.toolRouter.session.create).not.toHaveBeenCalled();
370 + });
371 +
372 + it('returns the same registrations from localTools()/localToolkits() and the deprecated methods', async () => {
373 + const session = await router.create('user_1', {
374 + experimental: { localTools: [customToolHandle], localToolkits: [devToolkit] },
375 + });
376 +
377 + expect(session.localTools()).toEqual([
378 + expect.objectContaining({ slug: 'LOCAL_GET_USER_CONTEXT' }),
379 + expect.objectContaining({ slug: 'LOCAL_DEV_TOOLS_GREP', toolkit: 'DEV_TOOLS' }),
380 + ]);
381 + expect(session.customTools()).toEqual(session.localTools());
382 + expect(session.customTools({ toolkit: 'dev_tools' })).toEqual(
383 + session.localTools({ toolkit: 'dev_tools' })
384 + );
385 + expect(session.localToolkits()).toEqual([
386 + expect.objectContaining({
387 + slug: 'DEV_TOOLS',
388 + tools: [expect.objectContaining({ slug: 'LOCAL_DEV_TOOLS_GREP' })],
389 + }),
390 + ]);
391 + expect(session.customToolkits()).toEqual(session.localToolkits());
392 + });
393 +});
394 +
395 // ────────────────────────────────────────────────────────────────
396 // ToolRouterSession — execution routing
397 // ────────────────────────────────────────────────────────────────
ts/packages/core/test/models/toolRouter.test.ts
+48
@@ -2054,9 +2054,12 @@ describe('ToolRouter', () => {
2054 ['toolkits', { toolkits: { disable: ['x'] } }],
2055 ['tools', { tools: { github: ['GITHUB_GET_REPO'] } }],
2056 ['tags', { tags: ['readOnlyHint'] }],
2057 + ['experimental.localTools', { experimental: { localTools: [customTool] } }],
2058 + ['experimental.localToolkits', { experimental: { localToolkits: [customToolkit] } }],
2059 ['experimental.customTools', { experimental: { customTools: [customTool] } }],
2060 ['experimental.customToolkits', { experimental: { customToolkits: [customToolkit] } }],
2061 ['toolkits', { toolkits: [] }],
2062 + ['experimental.localTools', { experimental: { localTools: [] } }],
2063 ['experimental.customTools', { experimental: { customTools: [] } }],
2064 ])(
2065 'rejects sessionConfigId combined with %s (%j) without calling the API',
@@ -3942,6 +3945,51 @@ describe('ToolRouter', () => {
3945 ]);
3946 });
3947
3948 + it('should attach local tools passed as localTools with the same wire payload', async () => {
3949 + const grepTool = createCustomTool('GREP', {
3950 + name: 'Grep',
3951 + description: 'Search local text',
3952 + inputParams: z.object({ pattern: z.string() }),
3953 + execute: vi.fn(async () => ({ matches: [] })),
3954 + });
3955 + const attachResponse = {
3956 + ...mockSessionRetrieveResponse,
3957 + experimental: {
3958 + custom_tools: [{ slug: 'LOCAL_GREP', original_slug: 'GREP', extends_toolkit: null }],
3959 + },
3960 + };
3961 + mockClient.toolRouter.session.attach
3962 + .mockResolvedValueOnce(attachResponse)
3963 + .mockResolvedValueOnce(attachResponse);
3964 +
3965 + const session = await toolRouter.use(sessionId, { localTools: [grepTool] });
3966 + await toolRouter.use(sessionId, { customTools: [grepTool] });
3967 +
3968 + const [[, localBody], [, customBody]] = mockClient.toolRouter.session.attach.mock.calls;
3969 + expect(localBody).toEqual({
3970 + experimental: { custom_tools: [expect.objectContaining({ slug: 'GREP' })] },
3971 + });
3972 + expect(customBody).toEqual(localBody);
3973 + expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
3974 + expect(session.localTools()).toEqual([expect.objectContaining({ slug: 'LOCAL_GREP' })]);
3975 + expect(session.customTools()).toEqual(session.localTools());
3976 + });
3977 +
3978 + it.each([
3979 + ['localTools or customTools', { localTools: [], customTools: [] }],
3980 + ['localToolkits or customToolkits', { localToolkits: [], customToolkits: [] }],
3981 + ])(
3982 + 'should reject passing both %s to use() without calling the API',
3983 + async (fields, options) => {
3984 + const error = await toolRouter.use(sessionId, options).catch(e => e);
3985 +
3986 + expect(error).toBeInstanceOf(ValidationError);
3987 + expect(error.message).toContain(`Pass either ${fields}, not both`);
3988 + expect(mockClient.toolRouter.session.attach).not.toHaveBeenCalled();
3989 + expect(mockClient.toolRouter.session.retrieve).not.toHaveBeenCalled();
3990 + }
3991 + );
3992 +
3993 it('should return a session with correct session ID', async () => {
3994 const customResponse = {
3995 ...mockSessionRetrieveResponse,
ts/packages/core/type-tests/local-tools.test-d.ts new
+57
@@ -0,0 +1,57 @@
1 +/**
2 + * Type-level tests for the local tools rename. The deprecated `custom*` names
3 + * must stay interchangeable with the `local*` names so existing code compiles.
4 + */
5 +import {
6 + Composio,
7 + experimental_createTool,
8 + experimental_createToolkit,
9 + type CustomTool,
10 + type CustomToolkit,
11 + type LocalTool,
12 + type LocalToolkit,
13 + type RegisteredCustomTool,
14 + type RegisteredCustomToolkit,
15 + type RegisteredLocalTool,
16 + type RegisteredLocalToolkit,
17 +} from '../src';
18 +import type {
19 + CreateCustomToolParams,
20 + CreateLocalToolParams,
21 + CustomTool as ExperimentalCustomTool,
22 + LocalTool as ExperimentalLocalTool,
23 +} from '../src/experimental';
24 +import type { z } from 'zod/v3';
25 +
26 +declare const composio: Composio;
27 +declare const localTool: ReturnType<typeof experimental_createTool>;
28 +declare const localToolkit: ReturnType<typeof experimental_createToolkit>;
29 +declare const legacyParams: CreateCustomToolParams<z.ZodTypeAny>;
30 +
31 +async function localToolsAliases(): Promise<void> {
32 + const asLocal: LocalTool = localTool;
33 + const asCustom: CustomTool = asLocal;
34 + const backToLocal: ExperimentalLocalTool = asCustom satisfies ExperimentalCustomTool;
35 + const toolkit: LocalToolkit = localToolkit satisfies CustomToolkit;
36 + void backToLocal;
37 +
38 + const params: CreateLocalToolParams<z.ZodTypeAny> = legacyParams;
39 + void params;
40 +
41 + const session = await composio.create('u', {
42 + experimental: { localTools: [asCustom], localToolkits: [toolkit] },
43 + });
44 + const tools: RegisteredLocalTool[] = session.customTools();
45 + const legacyTools: RegisteredCustomTool[] = session.localTools({ toolkit: 'DEV_TOOLS' });
46 + const toolkits: RegisteredLocalToolkit[] = session.customToolkits();
47 + const legacyToolkits: RegisteredCustomToolkit[] = session.localToolkits();
48 + void [tools, legacyTools, toolkits, legacyToolkits];
49 +
50 + await composio.sessions.use('session_123', { localTools: [asLocal], localToolkits: [toolkit] });
51 + await composio.use('session_123', {
52 + customTools: [asLocal],
53 + customToolkits: [toolkit],
54 + mcp: true,
55 + });
56 +}
57 +void localToolsAliases;
ts/packages/core/type-tests/session-configs.test-d.ts
+39 -9
@@ -64,8 +64,8 @@ function summaryMatchesClient(
64
65 // A saved Session config replaces the inline access fields on create. Each
66 // forbidden field is rejected on every create entry point.
67 -declare const customTool: ReturnType<typeof experimental_createTool>;
68 -declare const customToolkit: ReturnType<typeof experimental_createToolkit>;
67 +declare const localTool: ReturnType<typeof experimental_createTool>;
68 +declare const localToolkit: ReturnType<typeof experimental_createToolkit>;
69
70 async function createRejectsMixedInputs(): Promise<void> {
71 const experimental = { sessionConfigId: 'sc_1' };
@@ -76,13 +76,21 @@ async function createRejectsMixedInputs(): Promise<void> {
76 await composio.create('u', { tools: { github: ['GITHUB_GET_REPO'] }, experimental });
77 // @ts-expect-error tags cannot be combined with sessionConfigId
78 await composio.create('u', { tags: ['readOnlyHint'], experimental });
79 + await composio.create('u', {
80 + // @ts-expect-error localTools cannot be combined with sessionConfigId
81 + experimental: { sessionConfigId: 'sc_1', localTools: [localTool] },
82 + });
83 await composio.create('u', {
84 // @ts-expect-error customTools cannot be combined with sessionConfigId
81 - experimental: { sessionConfigId: 'sc_1', customTools: [customTool] },
85 + experimental: { sessionConfigId: 'sc_1', customTools: [localTool] },
86 + });
87 + await composio.create('u', {
88 + // @ts-expect-error localToolkits cannot be combined with sessionConfigId
89 + experimental: { sessionConfigId: 'sc_1', localToolkits: [localToolkit] },
90 });
91 await composio.create('u', {
92 // @ts-expect-error customToolkits cannot be combined with sessionConfigId
85 - experimental: { sessionConfigId: 'sc_1', customToolkits: [customToolkit] },
93 + experimental: { sessionConfigId: 'sc_1', customToolkits: [localToolkit] },
94 });
95
96 // @ts-expect-error toolkits cannot be combined with sessionConfigId
@@ -91,13 +99,21 @@ async function createRejectsMixedInputs(): Promise<void> {
99 await composio.sessions.create('u', { tools: { github: ['GITHUB_GET_REPO'] }, experimental });
100 // @ts-expect-error tags cannot be combined with sessionConfigId
101 await composio.sessions.create('u', { tags: ['readOnlyHint'], experimental });
102 + await composio.sessions.create('u', {
103 + // @ts-expect-error localTools cannot be combined with sessionConfigId
104 + experimental: { sessionConfigId: 'sc_1', localTools: [localTool] },
105 + });
106 await composio.sessions.create('u', {
107 // @ts-expect-error customTools cannot be combined with sessionConfigId
96 - experimental: { sessionConfigId: 'sc_1', customTools: [customTool] },
108 + experimental: { sessionConfigId: 'sc_1', customTools: [localTool] },
109 + });
110 + await composio.sessions.create('u', {
111 + // @ts-expect-error localToolkits cannot be combined with sessionConfigId
112 + experimental: { sessionConfigId: 'sc_1', localToolkits: [localToolkit] },
113 });
114 await composio.sessions.create('u', {
115 // @ts-expect-error customToolkits cannot be combined with sessionConfigId
100 - experimental: { sessionConfigId: 'sc_1', customToolkits: [customToolkit] },
116 + experimental: { sessionConfigId: 'sc_1', customToolkits: [localToolkit] },
117 });
118
119 // @ts-expect-error toolkits cannot be combined with sessionConfigId
@@ -106,15 +122,25 @@ async function createRejectsMixedInputs(): Promise<void> {
122 await composio.create('u', { mcp: true, tools: { github: ['GITHUB_GET_REPO'] }, experimental });
123 // @ts-expect-error tags cannot be combined with sessionConfigId
124 await composio.create('u', { mcp: true, tags: ['readOnlyHint'], experimental });
125 + await composio.create('u', {
126 + mcp: true,
127 + // @ts-expect-error localTools cannot be combined with sessionConfigId
128 + experimental: { sessionConfigId: 'sc_1', localTools: [localTool] },
129 + });
130 await composio.create('u', {
131 mcp: true,
132 // @ts-expect-error customTools cannot be combined with sessionConfigId
112 - experimental: { sessionConfigId: 'sc_1', customTools: [customTool] },
133 + experimental: { sessionConfigId: 'sc_1', customTools: [localTool] },
134 + });
135 + await composio.create('u', {
136 + mcp: true,
137 + // @ts-expect-error localToolkits cannot be combined with sessionConfigId
138 + experimental: { sessionConfigId: 'sc_1', localToolkits: [localToolkit] },
139 });
140 await composio.create('u', {
141 mcp: true,
142 // @ts-expect-error customToolkits cannot be combined with sessionConfigId
117 - experimental: { sessionConfigId: 'sc_1', customToolkits: [customToolkit] },
143 + experimental: { sessionConfigId: 'sc_1', customToolkits: [localToolkit] },
144 });
145 }
146
@@ -163,7 +189,11 @@ async function createInline(): Promise<void> {
189 toolkits: ['github'],
190 tools: { github: ['GITHUB_GET_REPO'] },
191 tags: ['readOnlyHint'],
166 - experimental: { customTools: [customTool], customToolkits: [customToolkit] },
192 + experimental: { localTools: [localTool], localToolkits: [localToolkit] },
193 + });
194 + // Deprecated aliases still compile.
195 + await composio.create('u', {
196 + experimental: { customTools: [localTool], customToolkits: [localToolkit] },
197 });
198 await composio.create('u', { mcp: true, toolkits: { disable: ['gmail'] } });
199 }
ts/packages/core/type-tests/sessions-mcp.test-d.ts
+1
@@ -44,6 +44,7 @@ async function requestOptionsArg(): Promise<void> {
44 await composio.create('user_123', { toolkits: ['gmail'] }, { signal: ctrl.signal });
45 await composio.create('user_123', { mcp: true }, { signal: ctrl.signal });
46 await composio.sessions.create('user_123', undefined, { signal: ctrl.signal });
47 + await composio.use('session_123', { localTools: [] }, { signal: ctrl.signal });
48 await composio.use('session_123', { customTools: [] }, { signal: ctrl.signal });
49 await composio.use('session_123', { mcp: true }, { signal: ctrl.signal });
50 }