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.
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();
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
381
return {
382
byFinalSlug,
383
byOriginalSlug,
384
+ byToolkitAndOriginalSlug,
385
+ ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
386
toolkits,
387
tools: tools.length ? tools : undefined,
388
};
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
568
return {
569
byFinalSlug,
570
byOriginalSlug,
571
+ byToolkitAndOriginalSlug,
572
+ ...(ambiguousOriginalSlugs.size ? { ambiguousOriginalSlugs } : {}),
573
toolkits,
574
tools: tools.length ? tools : undefined,
575
};
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
*
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
});