Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
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.tsindex 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.tsindex 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 executionconst executeParams: SessionExecuteParams = {diff --git a/ts/packages/core/src/models/ToolRouterSession.ts b/ts/packages/core/src/models/ToolRouterSession.tsindex 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 executionconst 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.tsindex 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.tsindex 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. */