Skip to content

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

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

Rahul Tarakd31efcb1604c
diff --git a/ts/packages/core/src/models/CustomTool.ts b/ts/packages/core/src/models/CustomTool.ts
index 5741e0fdd..3118a2a3d 100644
--- a/ts/packages/core/src/models/CustomTool.ts
+++ b/ts/packages/core/src/models/CustomTool.ts
@@ -271,6 +271,47 @@ function buildFinalSlug(toolSlug: string, toolkitSlug?: string): string {
: `${LOCAL_TOOL_PREFIX}${upper}`;
}
+const qualifiedOriginalSlugKey = (toolkit: string | undefined, originalSlug: string): string =>
+ `${toolkit?.toUpperCase() ?? ''}::${originalSlug.toUpperCase()}`;
+
+const canShareOriginalSlug = (existing: CustomToolsMapEntry, next: CustomToolsMapEntry): boolean =>
+ !!existing.toolkit &&
+ !!next.toolkit &&
+ existing.toolkit.toLowerCase() !== next.toolkit.toLowerCase();
+
+const addOriginalSlugAlias = (params: {
+ byOriginalSlug: Map<string, CustomToolsMapEntry>;
+ ambiguousOriginalSlugs: Set<string>;
+ originalSlug: string;
+ entry: CustomToolsMapEntry;
+}) => {
+ const originalSlugKey = params.originalSlug.toUpperCase();
+ if (params.ambiguousOriginalSlugs.has(originalSlugKey)) {
+ return;
+ }
+
+ const existing = params.byOriginalSlug.get(originalSlugKey);
+ if (!existing) {
+ params.byOriginalSlug.set(originalSlugKey, params.entry);
+ return;
+ }
+
+ if (existing.finalSlug.toUpperCase() === params.entry.finalSlug.toUpperCase()) {
+ return;
+ }
+
+ if (canShareOriginalSlug(existing, params.entry)) {
+ params.byOriginalSlug.delete(originalSlugKey);
+ params.ambiguousOriginalSlugs.add(originalSlugKey);
+ return;
+ }
+
+ throw new ValidationError(
+ `Custom tool slug collision: original slug "${params.originalSlug}" maps to multiple final slugs. ` +
+ `"${existing.finalSlug}" and "${params.entry.finalSlug}" both resolve from "${originalSlugKey}".`
+ );
+};
+
/**
* Build a CustomToolsMap from custom tools and toolkits.
* Used internally by ToolRouter.create() to construct the per-session routing map.
@@ -287,6 +328,8 @@ export function buildCustomToolsMap(
): CustomToolsMap {
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
+ const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
+ const ambiguousOriginalSlugs = new Set<string>();
const addEntry = (handle: CustomTool, finalSlug: string, toolkit?: string) => {
const originalSlug = handle.slug.toUpperCase();
@@ -308,17 +351,17 @@ export function buildCustomToolsMap(
);
}
- // Check cross-group collisions on original slug
- if (byOriginalSlug.has(originalSlug)) {
+ const qualifiedKey = qualifiedOriginalSlugKey(toolkit, originalSlug);
+ if (byToolkitAndOriginalSlug.has(qualifiedKey)) {
throw new ValidationError(
- `Custom tool slug collision: original slug "${handle.slug}" maps to multiple final slugs. ` +
- `"${byOriginalSlug.get(originalSlug)!.finalSlug}" and "${finalSlug}" both resolve from "${originalSlug}".`
+ `Custom tool slug collision: original slug "${handle.slug}" is already registered for toolkit "${toolkit ?? 'custom'}".`
);
}
const entry: CustomToolsMapEntry = { handle, finalSlug, toolkit };
byFinalSlug.set(finalSlugKey, entry);
- byOriginalSlug.set(originalSlug, entry);
+ byToolkitAndOriginalSlug.set(qualifiedKey, entry);
+ addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
};
// Process standalone tools
@@ -338,6 +381,8 @@ export function buildCustomToolsMap(
return {
byFinalSlug,
byOriginalSlug,
+ byToolkitAndOriginalSlug,
+ ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
toolkits,
tools: tools.length ? tools : undefined,
};
@@ -444,34 +489,64 @@ export function buildCustomToolsMapFromResponse(
): CustomToolsMap {
const byFinalSlug = new Map<string, CustomToolsMapEntry>();
const byOriginalSlug = new Map<string, CustomToolsMapEntry>();
+ const byToolkitAndOriginalSlug = new Map<string, CustomToolsMapEntry>();
+ const ambiguousOriginalSlugs = new Set<string>();
+
+ type HandleMatch = { handle: CustomTool; toolkit?: string };
+ const handlesByQualifiedOriginalSlug = new Map<string, HandleMatch>();
+ const handlesByOriginalSlug = new Map<string, HandleMatch[]>();
+
+ const registerHandle = (handle: CustomTool, toolkit?: string) => {
+ const originalSlug = handle.slug.toUpperCase();
+ const match = { handle, toolkit };
+ handlesByQualifiedOriginalSlug.set(qualifiedOriginalSlugKey(toolkit, originalSlug), match);
+ const existing = handlesByOriginalSlug.get(originalSlug) ?? [];
+ existing.push(match);
+ handlesByOriginalSlug.set(originalSlug, existing);
+ };
- // Build a lookup from original slug → custom tool handle (for matching response items)
- const handlesByOriginalSlug = new Map<string, { handle: CustomTool; toolkit?: string }>();
for (const handle of tools) {
- handlesByOriginalSlug.set(handle.slug.toUpperCase(), {
- handle,
- toolkit: handle.extendsToolkit,
- });
+ registerHandle(handle, handle.extendsToolkit);
}
if (toolkits) {
for (const tk of toolkits) {
for (const handle of tk.tools) {
- handlesByOriginalSlug.set(handle.slug.toUpperCase(), { handle, toolkit: tk.slug });
+ registerHandle(handle, tk.slug);
}
}
}
- const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string) => {
- const match = handlesByOriginalSlug.get(originalSlug.toUpperCase());
+ const findHandle = (originalSlug: string, toolkit?: string): HandleMatch | undefined => {
+ const originalSlugKey = originalSlug.toUpperCase();
+ const qualifiedMatch = handlesByQualifiedOriginalSlug.get(
+ qualifiedOriginalSlugKey(toolkit, originalSlugKey)
+ );
+ if (qualifiedMatch) return qualifiedMatch;
+
+ const bareMatches = handlesByOriginalSlug.get(originalSlugKey) ?? [];
+ return bareMatches.length === 1 ? bareMatches[0] : undefined;
+ };
+
+ const addEntry = (finalSlug: string, originalSlug: string, toolkit?: string | null) => {
+ const resolvedToolkit = toolkit ?? undefined;
+ const match = findHandle(originalSlug, resolvedToolkit);
if (!match) return; // Response tool not found in our handles (shouldn't happen)
+ const finalSlugKey = finalSlug.toUpperCase();
+ if (byFinalSlug.has(finalSlugKey)) {
+ throw new ValidationError(
+ `Custom tool slug collision: "${finalSlug}" is already registered.`
+ );
+ }
+
const entry: CustomToolsMapEntry = {
handle: match.handle,
finalSlug,
- toolkit: toolkit ?? match.toolkit,
+ toolkit: resolvedToolkit ?? match.toolkit,
};
- byFinalSlug.set(finalSlug.toUpperCase(), entry);
- byOriginalSlug.set(originalSlug.toUpperCase(), entry);
+ byFinalSlug.set(finalSlugKey, entry);
+ byToolkitAndOriginalSlug.set(qualifiedOriginalSlugKey(entry.toolkit, originalSlug), entry);
+ addOriginalSlugAlias({ byOriginalSlug, ambiguousOriginalSlugs, originalSlug, entry });
};
// Map standalone custom tools from response
@@ -493,6 +568,8 @@ export function buildCustomToolsMapFromResponse(
return {
byFinalSlug,
byOriginalSlug,
+ byToolkitAndOriginalSlug,
+ ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
toolkits,
tools: tools.length ? tools : undefined,
};
@@ -510,6 +587,19 @@ export function findCustomToolMapEntryByFinalSlug(
return customToolsMap?.byFinalSlug.get(slug.toUpperCase());
}
+/**
+ * Find a custom toolkit tool entry by toolkit slug and original tool slug.
+ *
+ * @internal
+ */
+export function findCustomToolMapEntryByToolkitAndOriginalSlug(
+ customToolsMap: CustomToolsMap | undefined,
+ toolkit: string | undefined,
+ slug: string
+): CustomToolsMapEntry | undefined {
+ return customToolsMap?.byToolkitAndOriginalSlug?.get(qualifiedOriginalSlugKey(toolkit, slug));
+}
+
/**
* Reject legacy attempts to preload custom tools through top-level preload.tools.
*
@@ -534,6 +624,7 @@ export function assertNoCustomToolSlugsInPreload(
// Custom tools use `preload: true` on their SDK definitions instead.
normalized.startsWith(LOCAL_TOOL_PREFIX) ||
customToolsMap?.byOriginalSlug.has(normalized) ||
+ customToolsMap?.ambiguousOriginalSlugs?.has(normalized) ||
customToolsMap?.byFinalSlug.has(normalized)
);
});
diff --git a/ts/packages/core/src/models/SessionContext.ts b/ts/packages/core/src/models/SessionContext.ts
index 045e12902..d338a69bb 100644
--- a/ts/packages/core/src/models/SessionContext.ts
+++ b/ts/packages/core/src/models/SessionContext.ts
@@ -18,7 +18,11 @@ import {
} from '../types/toolRouter.types';
import { ValidationError } from '../errors';
import { transformProxyParams } from './proxyParamsTransform';
-import { findCustomTool, executeCustomTool } from './customToolExecution';
+import {
+ assertUnambiguousCustomToolSlug,
+ findCustomTool,
+ executeCustomTool,
+} from './customToolExecution';
import { transformExecuteResponse } from '../utils/transformers/toolRouterResponseTransform';
import type { SessionExecuteParams } from '@composio/client/resources/tool-router/session/session.mjs';
import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
@@ -66,6 +70,7 @@ export class SessionContextImpl implements SessionContext {
logId: '',
});
}
+ assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
// Fall back to remote execution
const executeParams: SessionExecuteParams = {
diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.ts
index 37d626a40..52c5b9afe 100644
--- a/ts/packages/core/src/models/ToolRouterSession.ts
+++ b/ts/packages/core/src/models/ToolRouterSession.ts
@@ -47,8 +47,15 @@ import type {
} from '@composio/client/resources/tool-router/session/session.mjs';
import { SessionProxyExecuteParamsSchema } from '../types/toolRouter.types';
import { SessionContextImpl } from './SessionContext';
-import { findCustomTool, executeCustomTool } from './customToolExecution';
-import { findCustomToolMapEntryByFinalSlug } from './CustomTool';
+import {
+ assertUnambiguousCustomToolSlug,
+ findCustomTool,
+ executeCustomTool,
+} from './customToolExecution';
+import {
+ findCustomToolMapEntryByFinalSlug,
+ findCustomToolMapEntryByToolkitAndOriginalSlug,
+} from './CustomTool';
import { transformProxyParams } from './proxyParamsTransform';
import { inlineCustomToolsExperimental } from './inlineCustomToolsPayload';
import { transformToolRouterUpdateParams } from '../lib/toolRouterParams';
@@ -142,6 +149,7 @@ export class ToolRouterSession<
if (customTool) {
return executeCustomTool(customTool, input, this.sessionContext!);
}
+ assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
return this.executeBackendSessionTool(
ToolsModel,
toolSlug,
@@ -275,8 +283,11 @@ export class ToolRouterSession<
name: tk.name,
description: tk.description,
tools: tk.tools.map(tool => {
- // Look up the entry to get the final slug
- const entry = this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());
+ // Look up by toolkit + original slug so toolkits can safely reuse common names
+ // like VERSION, CLICK, or SEARCH without losing the backend-assigned final slug.
+ const entry =
+ findCustomToolMapEntryByToolkitAndOriginalSlug(this.customToolsMap, tk.slug, tool.slug) ??
+ this.customToolsMap!.byOriginalSlug.get(tool.slug.toUpperCase());
return {
slug: entry?.finalSlug ?? tool.slug,
name: tool.name,
@@ -415,6 +426,7 @@ export class ToolRouterSession<
logId: '',
};
}
+ assertUnambiguousCustomToolSlug(this.customToolsMap, toolSlug);
// Remote execution
const executeParams: SessionExecuteParams = {
@@ -558,6 +570,7 @@ export class ToolRouterSession<
if (entry) {
localItems.push({ index: i, entry });
} else {
+ assertUnambiguousCustomToolSlug(this.customToolsMap, parsed[i].tool_slug);
remoteIndices.push(i);
}
}
diff --git a/ts/packages/core/src/models/customToolExecution.ts b/ts/packages/core/src/models/customToolExecution.ts
index 92eb256f4..803987610 100644
--- a/ts/packages/core/src/models/customToolExecution.ts
+++ b/ts/packages/core/src/models/customToolExecution.ts
@@ -2,8 +2,13 @@
* @fileoverview Standalone functions for custom tool lookup and execution.
* Extracted from ToolRouterSession for reuse in SessionContextImpl (sibling routing).
*/
-import type { CustomToolsMap, CustomToolsMapEntry, SessionContext } from '../types/customTool.types';
+import type {
+ CustomToolsMap,
+ CustomToolsMapEntry,
+ SessionContext,
+} from '../types/customTool.types';
import type { ToolExecuteResponse } from '../types/tool.types';
+import { ValidationError } from '../errors';
/**
* Find a custom tool entry by slug.
@@ -15,7 +20,36 @@ export function findCustomTool(
): CustomToolsMapEntry | undefined {
if (!map) return undefined;
const upper = slug.toUpperCase();
- return map.byFinalSlug.get(upper) ?? map.byOriginalSlug.get(upper);
+ const finalSlugMatch = map.byFinalSlug.get(upper);
+ if (finalSlugMatch) return finalSlugMatch;
+ if (map.ambiguousOriginalSlugs?.has(upper)) return undefined;
+ return map.byOriginalSlug.get(upper);
+}
+
+/**
+ * Reject ambiguous bare original slugs before falling through to backend execution.
+ * Agents receive final slugs (LOCAL_<TOOLKIT>_<TOOL>) from schemas, while bare original
+ * slugs are only a convenience for manual session.execute() calls when unique.
+ */
+export function assertUnambiguousCustomToolSlug(
+ map: CustomToolsMap | undefined,
+ slug: string
+): void {
+ if (!map) return;
+ const upper = slug.toUpperCase();
+ if (!map.ambiguousOriginalSlugs?.has(upper)) return;
+
+ const finalSlugs = [...map.byFinalSlug.values()]
+ .filter(entry => entry.handle.slug.toUpperCase() === upper)
+ .map(entry => entry.finalSlug)
+ .sort();
+ const hint = finalSlugs.length ? ` Use one of: ${finalSlugs.join(', ')}.` : '';
+
+ throw new ValidationError(
+ `Ambiguous custom tool slug "${slug}". Multiple custom toolkit tools share this original slug; ` +
+ `manual session.execute() by original slug is only supported when the original slug is unique.` +
+ hint
+ );
}
/**
diff --git a/ts/packages/core/src/types/customTool.types.ts b/ts/packages/core/src/types/customTool.types.ts
index f9e23b7d7..054575d81 100644
--- a/ts/packages/core/src/types/customTool.types.ts
+++ b/ts/packages/core/src/types/customTool.types.ts
@@ -256,8 +256,12 @@ export type CustomToolsMapEntry = {
export type CustomToolsMap = {
/** Lookup by final slug (e.g. LOCAL_GET_USER_CONTEXT) — used for agent execution path */
byFinalSlug: Map<string, CustomToolsMapEntry>;
- /** Lookup by original slug (e.g. GET_USER_CONTEXT) — used for programmatic session.execute() */
+ /** Lookup by unique original slug (e.g. GET_USER_CONTEXT) — used for programmatic session.execute() */
byOriginalSlug: Map<string, CustomToolsMapEntry>;
+ /** Lookup by resolved toolkit + original slug — used when multiple custom toolkits reuse tool names */
+ byToolkitAndOriginalSlug?: Map<string, CustomToolsMapEntry>;
+ /** Original slugs that appear in multiple toolkits and cannot be resolved safely without the final slug */
+ ambiguousOriginalSlugs?: Set<string>;
/** The original custom toolkits passed at session creation — used for session.customToolkits() */
toolkits?: CustomToolkit[];
/** The original standalone custom tools passed at session creation — kept for inline re-injection on later requests. */