@devries-cameron20 / composio Mirror · read-only / commits / d31efcb16
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, 21:00 UTC

fix(core): qualify custom toolkit child slug lookups (#3360)

## Summary - Fixes SDK custom-tool mapping for custom toolkits that reuse the same child tool slug, e.g. `APP_A.VERSION` and `APP_B.VERSION`. - Adds toolkit-qualified lookup (`toolkit + original slug`) while keeping bare original-slug lookup only when it is unambiguous. - Throws a client-side ambiguity error for manual `session.execute('VERSION')` when multiple custom toolkit tools share `VERSION`, instead of falling through to backend execution. - Keeps `session.customToolkits()` / `session.customTools()` mapped to the backend-assigned final slugs for duplicate child names. ## Repro / validation Validated locally with a temporary Tool Router script (not committed) using two dummy custom toolkits that both define `VERSION`: - Current `next` SDK fails before high-level use with `Custom tool slug collision: original slug "VERSION" maps to multiple final slugs...`. - Tool Router backend accepts the same payload and returns both `LOCAL_DUMMY_APP_A_REPRO_VERSION` and `LOCAL_DUMMY_APP_B_REPRO_VERSION`. - This branch builds the SDK map successfully and high-level SDK execution routes each final slug to its own internal handler: - `LOCAL_DUMMY_APP_A_REPRO_VERSION` -> `{ app: "A", version: "1.0.0" }` - `LOCAL_DUMMY_APP_B_REPRO_VERSION` -> `{ app: "B", version: "2.0.0" }` ## Tests - `pnpm --filter @composio/core typecheck` - `pnpm --filter @composio/core exec vitest run test/models/customTool.test.ts test/models/toolRouter.test.ts test/models/customToolRouting.test.ts`

Rahul Tarak committed May 7, 2026 at 05:28 UTC d31efcb1604c0340b76acfd57a7c90cd61993398
5 files changed +172 -25
ts/packages/core/src/models/CustomTool.ts
+108 -17
@@ -271,6 +271,47 @@ function buildFinalSlug(toolSlug: string, toolkitSlug?: string): string {
271 : `${LOCAL_TOOL_PREFIX}${upper}`;
272 }
273
274 +const qualifiedOriginalSlugKey = (toolkit: string | undefined, originalSlug: string): string =>
275 + `${toolkit?.toUpperCase() ?? ''}::${originalSlug.toUpperCase()}`;
276 +
277 +const canShareOriginalSlug = (existing: CustomToolsMapEntry, next: CustomToolsMapEntry): boolean =>
278 + !!existing.toolkit &&
279 + !!next.toolkit &&
280 + existing.toolkit.toLowerCase() !== next.toolkit.toLowerCase();
281 +
282 +const addOriginalSlugAlias = (params: {
283 + byOriginalSlug: Map<string, CustomToolsMapEntry>;
284 + ambiguousOriginalSlugs: Set<string>;
285 + originalSlug: string;
286 + entry: CustomToolsMapEntry;
287 +}) => {
288 + const originalSlugKey = params.originalSlug.toUpperCase();
289 + if (params.ambiguousOriginalSlugs.has(originalSlugKey)) {
290 + return;
291 + }
292 +
293 + const existing = params.byOriginalSlug.get(originalSlugKey);
294 + if (!existing) {
295 + params.byOriginalSlug.set(originalSlugKey, params.entry);
296 + return;
297 + }
298 +
299 + if (existing.finalSlug.toUpperCase() === params.entry.finalSlug.toUpperCase()) {
300 + return;
301 + }
302 +
303 + if (canShareOriginalSlug(existing, params.entry)) {
304 + params.byOriginalSlug.delete(originalSlugKey);
305 + params.ambiguousOriginalSlugs.add(originalSlugKey);
306 + return;
307 + }
308 +
309 + throw new ValidationError(
310 + `Custom tool slug collision: original slug "${params.originalSlug}" maps to multiple final slugs. ` +
311 + `"${existing.finalSlug}" and "${params.entry.finalSlug}" both resolve from "${originalSlugKey}".`
312 + );
313 +};
314 +
315 /**
316 * Build a CustomToolsMap from custom tools and toolkits.
317 * Used internally by ToolRouter.create() to construct the per-session routing map.
@@ -287,6 +328,8 @@ export function buildCustomToolsMap(
328 ): CustomToolsMap {
329 const byFinalSlug = new Map<string, CustomToolsMapEntry>();
330 const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
331 + const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
332 + const ambiguousOriginalSlugs = new Set<string>();
333
334 const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
335 const originalSlug = handle.slug.toUpperCase();
@@ -308,17 +351,17 @@ export function buildCustomToolsMap(
351 );
352 }
353
311 - // Check cross-group collisions on original slug
312 - if (byOriginalSlug.has(originalSlug)) {
354 + const qualifiedKey = qualifiedOriginalSlugKey(toolkit, originalSlug);
355 + if (byToolkitAndOriginalSlug.has(qualifiedKey)) {
356 throw new ValidationError(
314 - `Custom tool slug collision: original slug "${handle.slug}" maps to multiple final slugs. ` +
315 - `"${byOriginalSlug.get(originalSlug)!.finalSlug}" and "${finalSlug}" both resolve from "${originalSlug}".`
357 + `Custom tool slug collision: original slug "${handle.slug}" is already registered for toolkit "${toolkit ?? 'custom'}".`
358 );
359 }
360
361 const entry: CustomToolsMapEntry = { handle, finalSlug, toolkit };
362 byFinalSlug.set(finalSlugKey, entry);
321 - byOriginalSlug.set(originalSlug, entry);
363 + byToolkitAndOriginalSlug.set(qualifiedKey, entry);
364 + addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
365 };
366
367 // Process standalone tools
@@ -338,6 +381,8 @@ export function buildCustomToolsMap(
381 return {
382 byFinalSlug,
383 byOriginalSlug,
384 + byToolkitAndOriginalSlug,
385 + ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
386 toolkits,
387 tools: tools.length ? tools : undefined,
388 };
@@ -444,34 +489,64 @@ export function buildCustomToolsMapFromResponse(
489 ): CustomToolsMap {
490 const byFinalSlug = new Map<string, CustomToolsMapEntry>();
491 const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
492 + const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
493 + const ambiguousOriginalSlugs = new Set<string>();
494 +
495 + type HandleMatch = { handle: CustomTool; toolkit?: string };
496 + const handlesByQualifiedOriginalSlug = new Map<string, HandleMatch>();
497 + const handlesByOriginalSlug = new Map<string, HandleMatch[]>();
498 +
499 + const registerHandle = (handle: CustomTool, toolkit?: string) => {
500 + const originalSlug = handle.slug.toUpperCase();
501 + const match = { handle, toolkit };
502 + handlesByQualifiedOriginalSlug.set(qualifiedOriginalSlugKey(toolkit, originalSlug), match);
503 + const existing = handlesByOriginalSlug.get(originalSlug) ?? [];
504 + existing.push(match);
505 + handlesByOriginalSlug.set(originalSlug, existing);
506 + };
507
448 - // Build a lookup from original slug → custom tool handle (for matching response items)
449 - const handlesByOriginalSlug = new Map<string, { handle: CustomTool; toolkit?: string }>();
508 for (const handle of tools) {
451 - handlesByOriginalSlug.set(handle.slug.toUpperCase(), {
452 - handle,
453 - toolkit: handle.extendsToolkit,
454 - });
509 + registerHandle(handle, handle.extendsToolkit);
510 }
511 if (toolkits) {
512 for (const tk of toolkits) {
513 for (const handle of tk.tools) {
459 - handlesByOriginalSlug.set(handle.slug.toUpperCase(), { handle, toolkit: tk.slug });
514 + registerHandle(handle, tk.slug);
515 }
516 }
517 }
518
464 - const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string) => {
465 - const match = handlesByOriginalSlug.get(originalSlug.toUpperCase());
519 + const findHandle = (originalSlug: string, toolkit?: string): HandleMatch | undefined => {
520 + const originalSlugKey = originalSlug.toUpperCase();
521 + const qualifiedMatch = handlesByQualifiedOriginalSlug.get(
522 + qualifiedOriginalSlugKey(toolkit, originalSlugKey)
523 + );
524 + if (qualifiedMatch) return qualifiedMatch;
525 +
526 + const bareMatches = handlesByOriginalSlug.get(originalSlugKey) ?? [];
527 + return bareMatches.length === 1 ? bareMatches[0] : undefined;
528 + };
529 +
530 + const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string | null) => {
531 + const resolvedToolkit = toolkit ?? undefined;
532 + const match = findHandle(originalSlug, resolvedToolkit);
533 if (!match) return; // Response tool not found in our handles (shouldn't happen)
534
535 + const finalSlugKey = finalSlug.toUpperCase();
536 + if (byFinalSlug.has(finalSlugKey)) {
537 + throw new ValidationError(
538 + `Custom tool slug collision: "${finalSlug}" is already registered.`
539 + );
540 + }
541 +
542 const entry: CustomToolsMapEntry = {
543 handle: match.handle,
544 finalSlug,
471 - toolkit: toolkit ?? match.toolkit,
545 + toolkit: resolvedToolkit ?? match.toolkit,
546 };
473 - byFinalSlug.set(finalSlug.toUpperCase(), entry);
474 - byOriginalSlug.set(originalSlug.toUpperCase(), entry);
547 + byFinalSlug.set(finalSlugKey, entry);
548 + byToolkitAndOriginalSlug.set(qualifiedOriginalSlugKey(entry.toolkit, originalSlug), entry);
549 + addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
550 };
551
552 // Map standalone custom tools from response
@@ -493,6 +568,8 @@ export function buildCustomToolsMapFromResponse(
568 return {
569 byFinalSlug,
570 byOriginalSlug,
571 + byToolkitAndOriginalSlug,
572 + ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
573 toolkits,
574 tools: tools.length ? tools : undefined,
575 };
@@ -510,6 +587,19 @@ export function findCustomToolMapEntryByFinalSlug(
587 return customToolsMap?.byFinalSlug.get(slug.toUpperCase());
588 }
589
590 +/**
591 + * Find a custom toolkit tool entry by toolkit slug and original tool slug.
592 + *
593 + * @internal
594 + */
595 +export function findCustomToolMapEntryByToolkitAndOriginalSlug(
596 + customToolsMap: CustomToolsMap | undefined,
597 + toolkit: string | undefined,
598 + slug: string
599 +): CustomToolsMapEntry | undefined {
600 + return customToolsMap?.byToolkitAndOriginalSlug?.get(qualifiedOriginalSlugKey(toolkit, slug));
601 +}
602 +
603 /**
604 * Reject legacy attempts to preload custom tools through top-level preload.tools.
605 *
@@ -534,6 +624,7 @@ export function assertNoCustomToolSlugsInPreload(
624 // Custom tools use `preload: true` on their SDK definitions instead.
625 normalized.startsWith(LOCAL_TOOL_PREFIX) ||
626 customToolsMap?.byOriginalSlug.has(normalized) ||
627 + customToolsMap?.ambiguousOriginalSlugs?.has(normalized) ||
628 customToolsMap?.byFinalSlug.has(normalized)
629 );
630 });
ts/packages/core/src/models/SessionContext.ts
+6 -1
@@ -18,7 +18,11 @@ import {
18 } from '../types/toolRouter.types';
19 import { ValidationError } from '../errors';
20 import { transformProxyParams } from './proxyParamsTransform';
21 -import { findCustomTool, executeCustomTool } from './customToolExecution';
21 +import {
22 + assertUnambiguousCustomToolSlug,
23 + findCustomTool,
24 + executeCustomTool,
25 +} from './customToolExecution';
26 import { transformExecuteResponse } from '../utils/transformers/toolRouterResponseTransform';
27 import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
28 import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
@@ -66,6 +70,7 @@ export class SessionContextImpl implements SessionContext {
70 logId: '',
71 });
72 }
73 + assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
74
75 // Fall back to remote execution
76 const executeParams: SessionExecuteParams = {
ts/packages/core/src/models/ToolRouterSession.ts
+17 -4
@@ -47,8 +47,15 @@ import type {
47 } from '@composio/client/resources/tool-router/session/session.mjs';
48 import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
49 import { SessionContextImpl } from './SessionContext';
50 -import { findCustomTool, executeCustomTool } from './customToolExecution';
51 -import { findCustomToolMapEntryByFinalSlug } from './CustomTool';
50 +import {
51 + assertUnambiguousCustomToolSlug,
52 + findCustomTool,
53 + executeCustomTool,
54 +} from './customToolExecution';
55 +import {
56 + findCustomToolMapEntryByFinalSlug,
57 + findCustomToolMapEntryByToolkitAndOriginalSlug,
58 +} from './CustomTool';
59 import { transformProxyParams } from './proxyParamsTransform';
60 import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
61 import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';
@@ -142,6 +149,7 @@ export class ToolRouterSession<
149 if (customTool) {
150 return executeCustomTool(customTool, input, this.sessionContext!);
151 }
152 + assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
153 return this.executeBackendSessionTool(
154 ToolsModel,
155 toolSlug,
@@ -275,8 +283,11 @@ export class ToolRouterSession<
283 name: tk.name,
284 description: tk.description,
285 tools: tk.tools.map(tool => {
278 - // Look up the entry to get the final slug
279 - const entry = this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());
286 + // Look up by toolkit + original slug so toolkits can safely reuse common names
287 + // like VERSION, CLICK, or SEARCH without losing the backend-assigned final slug.
288 + const entry =
289 + findCustomToolMapEntryByToolkitAndOriginalSlug(this.customToolsMap, tk.slug, tool.slug) ??
290 + this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());
291 return {
292 slug: entry?.finalSlug ?? tool.slug,
293 name: tool.name,
@@ -415,6 +426,7 @@ export class ToolRouterSession<
426 logId: '',
427 };
428 }
429 + assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
430
431 // Remote execution
432 const executeParams: SessionExecuteParams = {
@@ -558,6 +570,7 @@ export class ToolRouterSession<
570 if (entry) {
571 localItems.push({ index: i, entry });
572 } else {
573 + assertUnambiguousCustomToolSlug(this.customToolsMap, parsed[i].tool_slug);
574 remoteIndices.push(i);
575 }
576 }
ts/packages/core/src/models/customToolExecution.ts
+36 -2
@@ -2,8 +2,13 @@
2 * @fileoverview Standalone functions for custom tool lookup and execution.
3 * Extracted from ToolRouterSession for reuse in SessionContextImpl (sibling routing).
4 */
5 -import type { CustomToolsMap, CustomToolsMapEntry, SessionContext } from '../types/customTool.types';
5 +import type {
6 + CustomToolsMap,
7 + CustomToolsMapEntry,
8 + SessionContext,
9 +} from '../types/customTool.types';
10 import type { ToolExecuteResponse } from '../types/tool.types';
11 +import { ValidationError } from '../errors';
12
13 /**
14 * Find a custom tool entry by slug.
@@ -15,7 +20,36 @@ export function findCustomTool(
20 ): CustomToolsMapEntry | undefined {
21 if (!map) return undefined;
22 const upper = slug.toUpperCase();
18 - return map.byFinalSlug.get(upper) ?? map.byOriginalSlug.get(upper);
23 + const finalSlugMatch = map.byFinalSlug.get(upper);
24 + if (finalSlugMatch) return finalSlugMatch;
25 + if (map.ambiguousOriginalSlugs?.has(upper)) return undefined;
26 + return map.byOriginalSlug.get(upper);
27 +}
28 +
29 +/**
30 + * Reject ambiguous bare original slugs before falling through to backend execution.
31 + * Agents receive final slugs (LOCAL_<TOOLKIT>_<TOOL>) from schemas, while bare original
32 + * slugs are only a convenience for manual session.execute() calls when unique.
33 + */
34 +export function assertUnambiguousCustomToolSlug(
35 + map: CustomToolsMap | undefined,
36 + slug: string
37 +): void {
38 + if (!map) return;
39 + const upper = slug.toUpperCase();
40 + if (!map.ambiguousOriginalSlugs?.has(upper)) return;
41 +
42 + const finalSlugs = [...map.byFinalSlug.values()]
43 + .filter(entry => entry.handle.slug.toUpperCase() === upper)
44 + .map(entry => entry.finalSlug)
45 + .sort();
46 + const hint = finalSlugs.length ? ` Use one of: ${finalSlugs.join(', ')}.` : '';
47 +
48 + throw new ValidationError(
49 + `Ambiguous custom tool slug "${slug}". Multiple custom toolkit tools share this original slug; ` +
50 + `manual session.execute() by original slug is only supported when the original slug is unique.` +
51 + hint
52 + );
53 }
54
55 /**
ts/packages/core/src/types/customTool.types.ts
+5 -1
@@ -256,8 +256,12 @@ export type CustomToolsMapEntry = {
256 export type CustomToolsMap = {
257 /** Lookup by final slug (e.g. LOCAL_GET_USER_CONTEXT) — used for agent execution path */
258 byFinalSlug: Map<string, CustomToolsMapEntry>;
259 - /** Lookup by original slug (e.g. GET_USER_CONTEXT) — used for programmatic session.execute() */
259 + /** Lookup by unique original slug (e.g. GET_USER_CONTEXT) — used for programmatic session.execute() */
260 byOriginalSlug: Map<string, CustomToolsMapEntry>;
261 + /** Lookup by resolved toolkit + original slug — used when multiple custom toolkits reuse tool names */
262 + byToolkitAndOriginalSlug?: Map<string, CustomToolsMapEntry>;
263 + /** Original slugs that appear in multiple toolkits and cannot be resolved safely without the final slug */
264 + ambiguousOriginalSlugs?: Set<string>;
265 /** The original custom toolkits passed at session creation — used for session.customToolkits() */
266 toolkits?: CustomToolkit[];
267 /** The original standalone custom tools passed at session creation — kept for inline re-injection on later requests. */