Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪇 feat: Consolidate Orchestration Into a Native Tool (#16744)
lia-by-librechat[bot]0042d9a231b4
diff --git a/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx b/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsxindex ec2a08358a..ace88067b6 100644--- a/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/AdvancedPanel.tsx@@ -1,23 +1,24 @@import { useState } from 'react';-import { useFormContext } from 'react-hook-form';import { ChevronLeft, Check, Copy } from 'lucide-react';+import { AgentCapabilities } from 'librechat-data-provider';+import { Controller, useFormContext } from 'react-hook-form';import { Button, TooltipAnchor, labelVariants, useToastContext } from '@librechat/client';import type { AgentForm } from '~/common';import { useAgentPanelContext } from '~/Providers';-import OrchestrationHub from './OrchestrationHub';import MaxAgentSteps from './MaxAgentSteps';import { groupHeadingClass } from './ui';+import AgentChain from './AgentChain';import { useLocalize } from '~/hooks';import { Panel } from '~/common';export default function AdvancedPanel() {const localize = useLocalize();const { showToast } = useToastContext();- const { watch } = useFormContext<AgentForm>();+ const { watch, control } = useFormContext<AgentForm>();const currentAgentId = watch('id');const [copied, setCopied] = useState(false);- const { setActivePanel } = useAgentPanelContext();+ const { setActivePanel, agentsConfig } = useAgentPanelContext();const handleCopyAgentId = async () => {if (!currentAgentId) return;@@ -58,7 +59,14 @@ export default function AdvancedPanel() {<MaxAgentSteps /></section>- <OrchestrationHub currentAgentId={currentAgentId} />+ {agentsConfig?.capabilities.includes(AgentCapabilities.chain) && (+ <Controller+ name="agent_ids"+ control={control}+ defaultValue={[]}+ render={({ field }) => <AgentChain field={field} currentAgentId={currentAgentId} />}+ />+ )}{currentAgentId && (<div className="border-border-light flex items-center justify-between gap-2 border-t pt-3">diff --git a/client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsx b/client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsxindex 05c0920f7f..5c44e33bfd 100644--- a/client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/AgentHandoffs.tsx@@ -1,4 +1,4 @@-import React, { useState, useMemo, useEffect } from 'react';+import React, { useState, useMemo } from 'react';import { Waypoints, ChevronDown } from 'lucide-react';import { Button, Label, Input, Textarea } from '@librechat/client';import type { ControllerRenderProps } from 'react-hook-form';@@ -11,6 +11,7 @@ import {AgentSelectInline,useSelectableAgents,} from './AgentList';+import { isHandoffEdge } from '../Tools/items/orchestration';import OrchestrationPattern from './OrchestrationPattern';import { useLocalize } from '~/hooks';import { CountPill } from './ui';@@ -31,9 +32,11 @@ const getTargetAgentId = (to: string | string[]): string => (Array.isArray(to) ?const AgentHandoffs: React.FC<AgentHandoffsProps> = ({ field, currentAgentId }) => {const localize = useLocalize();- const [newAgentId, setNewAgentId] = useState('');const [expandedIndices, setExpandedIndices] = useState<Set<number>>(new Set());- const edges = useMemo(() => field.value ?? [], [field.value]);+ const edges = useMemo(() => (field.value ?? []).filter(isHandoffEdge), [field.value]);+ const setEdges = (next: GraphEdge[]) => {+ field.onChange([...(field.value ?? []).filter((edge) => !isHandoffEdge(edge)), ...next]);+ };const { options, getAgent } = useSelectableAgents({ currentAgentId });const selectedAgentIds = useMemo(@@ -60,20 +63,15 @@ const AgentHandoffs: React.FC<AgentHandoffsProps> = ({ field, currentAgentId })[options, selectedAgentIds, edges],);- useEffect(() => {- if (!newAgentId) {+ const addHandoff = (agentId: string) => {+ if (!agentId || edges.length >= MAX_HANDOFFS || selectedAgentIds.has(agentId)) {return;}-- if (edges.length < MAX_HANDOFFS && !selectedAgentIds.has(newAgentId)) {- const newEdge: GraphEdge = { from: currentAgentId, to: newAgentId, edgeType: 'handoff' };- field.onChange([...edges, newEdge]);- }- setNewAgentId('');- }, [newAgentId, edges, field, currentAgentId, selectedAgentIds]);+ setEdges([...edges, { from: currentAgentId, to: agentId, edgeType: 'handoff' }]);+ };const removeHandoffAt = (index: number) => {- field.onChange(edges.filter((_, i) => i !== index));+ setEdges(edges.filter((_, i) => i !== index));setExpandedIndices((prev) =>new Set(@@ -94,13 +92,13 @@ const AgentHandoffs: React.FC<AgentHandoffsProps> = ({ field, currentAgentId })const updated = [...edges];updated[index] = { ...updated[index], to: agentId };- field.onChange(updated);+ setEdges(updated);};const updateHandoffDetailsAt = (index: number, updates: Partial<GraphEdge>) => {const updated = [...edges];updated[index] = { ...updated[index], ...updates };- field.onChange(updated);+ setEdges(updated);};const toggleExpanded = (index: number) => {@@ -247,7 +245,7 @@ const AgentHandoffs: React.FC<AgentHandoffsProps> = ({ field, currentAgentId }){edges.length > 0 && <Connector />}<AddAgentSelectoptions={addAgentOptions}- onSelect={setNewAgentId}+ onSelect={addHandoff}placeholder={localize('com_ui_agent_handoff_add')}ariaLabel={localize('com_ui_agent_var', { 0: localize('com_ui_add') })}/>diff --git a/client/src/components/SidePanel/Agents/Advanced/AgentList.tsx b/client/src/components/SidePanel/Agents/Advanced/AgentList.tsxindex 5099880763..0e4fa6e723 100644--- a/client/src/components/SidePanel/Agents/Advanced/AgentList.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/AgentList.tsx@@ -1,4 +1,4 @@-import { useMemo } from 'react';+import { useMemo, useContext, createContext } from 'react';import { X, PlusCircle } from 'lucide-react';import { EModelEndpoint } from 'librechat-data-provider';import { Button, ControlCombobox } from '@librechat/client';@@ -9,6 +9,8 @@ import MessageIcon from '~/components/Share/MessageIcon';import { useAgentsMapContext } from '~/Providers';import { useLocalize } from '~/hooks';+export const AgentPickerPortalContext = createContext<HTMLElement | null>(null);+const AGENT_MESSAGE = { endpoint: EModelEndpoint.agents, isCreatedByUser: false } as TMessage;/** Renders an agent's avatar/icon as used in combobox options and select triggers. */@@ -74,9 +76,11 @@ interface AddAgentSelectProps {/** Dashed "+ Add agent" combobox shared by every orchestration pattern. */export function AddAgentSelect({ options, onSelect, placeholder, ariaLabel }: AddAgentSelectProps) {const localize = useLocalize();+ const portalElement = useContext(AgentPickerPortalContext) ?? undefined;return (<ControlComboboxisCollapsed={false}+ portalElement={portalElement}ariaLabel={ariaLabel}selectedValue=""setValue={onSelect}@@ -109,9 +113,11 @@ export function AgentSelectInline({ariaLabel,}: AgentSelectInlineProps) {const localize = useLocalize();+ const portalElement = useContext(AgentPickerPortalContext) ?? undefined;return (<ControlComboboxisCollapsed={false}+ portalElement={portalElement}ariaLabel={ariaLabel}selectedValue={selectedValue}setValue={onChange}diff --git a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsxindex e566356d62..2f9abe47b4 100644--- a/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx+++ b/client/src/components/SidePanel/Agents/Advanced/OrchestrationHub.tsx@@ -6,7 +6,6 @@ import { useAgentPanelContext } from '~/Providers';import AgentSubagents from './AgentSubagents';import AgentHandoffs from './AgentHandoffs';import { groupHeadingClass } from './ui';-import AgentChain from './AgentChain';import { useLocalize } from '~/hooks';interface OrchestrationHubProps {@@ -14,9 +13,7 @@ interface OrchestrationHubProps {}/**- * Unifies the multi-agent collaboration patterns (delegate / hand off / chain)- * into a single hub with one shared visual language. Each pattern is gated by- * the agent endpoint's enabled capabilities; handoffs are always available.+ * Settings for the native orchestration tool. Handoffs are always available.*/export default function OrchestrationHub({ currentAgentId }: OrchestrationHubProps) {const localize = useLocalize();@@ -27,19 +24,15 @@ export default function OrchestrationHub({ currentAgentId }: OrchestrationHubPro() => agentsConfig?.capabilities.includes(AgentCapabilities.subagents) ?? false,[agentsConfig],);- const chainEnabled = useMemo(- () => agentsConfig?.capabilities.includes(AgentCapabilities.chain) ?? false,- [agentsConfig],- );const maxSubagents = agentsConfig?.maxSubagents ?? MAX_SUBAGENTS;return (<section className="flex flex-col gap-1"><div className="flex flex-col gap-0.5"><span className={groupHeadingClass}>{localize('com_ui_agent_orchestration')}</span>- <p className="text-xs text-text-secondary">{localize('com_ui_agent_orchestration_hint')}</p>+ <p className="text-text-secondary text-xs">{localize('com_ui_agent_orchestration_hint')}</p></div>- <div className="divide-y divide-border-light">+ <div className="divide-border-light divide-y">{subagentsEnabled && (<Controllername="subagents"@@ -60,14 +53,6 @@ export default function OrchestrationHub({ currentAgentId }: OrchestrationHubProdefaultValue={[]}render={({ field }) => <AgentHandoffs field={field} currentAgentId={currentAgentId} />}/>- {chainEnabled && (- <Controller- name="agent_ids"- control={control}- defaultValue={[]}- render={({ field }) => <AgentChain field={field} currentAgentId={currentAgentId} />}- />- )}</div></section>);diff --git a/client/src/components/SidePanel/Agents/Advanced/__tests__/AgentHandoffs.spec.tsx b/client/src/components/SidePanel/Agents/Advanced/__tests__/AgentHandoffs.spec.tsxnew file mode 100644index 0000000000..e2b4a2cda3--- /dev/null+++ b/client/src/components/SidePanel/Agents/Advanced/__tests__/AgentHandoffs.spec.tsx@@ -0,0 +1,77 @@+import { Controller, useForm } from 'react-hook-form';+import { act, fireEvent, render, screen, waitFor } from '@testing-library/react';+import type { GraphEdge } from 'librechat-data-provider';+import type { UseFormReturn } from 'react-hook-form';+import type { ReactNode } from 'react';+import type { AgentForm } from '~/common';+import AgentHandoffs from '../AgentHandoffs';++let mockSelect: (id: string) => void;+let mockGetValues: UseFormReturn<AgentForm>['getValues'];+const mockSubmit = jest.fn();+jest.mock('~/hooks', () => ({ useLocalize: () => (key: string) => key }));+jest.mock('../AgentList', () => ({+ AddAgentSelect: ({ onSelect }: { onSelect: (id: string) => void }) => {+ mockSelect = onSelect;+ return null;+ },+ AgentRow: ({+ children,+ onRemove,+ removeLabel,+ }: {+ children: ReactNode;+ onRemove: () => void;+ removeLabel: string;+ }) => (+ <div>+ {children}+ <button type="button" onClick={onRemove} aria-label={removeLabel} />+ </div>+ ),+ AgentSelectInline: () => null,+ agentIcon: () => null,+ useSelectableAgents: () => ({ options: [], getAgent: () => undefined }),+}));+jest.mock('../OrchestrationPattern', () => ({+ __esModule: true,+ default: ({ children }: { children: ReactNode }) => <div>{children}</div>,+}));++function Harness({ edges = [] }: { edges?: GraphEdge[] }) {+ const methods = useForm<AgentForm>({ defaultValues: { edges } });+ mockGetValues = methods.getValues;+ return (+ <form aria-label="agent form" onSubmit={methods.handleSubmit(mockSubmit)}>+ <Controller+ name="edges"+ control={methods.control}+ render={({ field }) => <AgentHandoffs field={field} currentAgentId="parent" />}+ />+ </form>+ );+}++test('commits a handoff before immediate submission without touching non-handoff edges', async () => {+ const direct: GraphEdge = { from: 'parent', to: 'other', edgeType: 'direct' };+ render(<Harness edges={[direct]} />);+ act(() => {+ mockSelect('child');+ fireEvent.submit(screen.getByRole('form', { name: 'agent form' }));+ });+ const edges = [direct, { from: 'parent', to: 'child', edgeType: 'handoff' }];+ expect(mockGetValues('edges')).toEqual(edges);+ await waitFor(() =>+ expect(mockSubmit).toHaveBeenCalledWith(expect.objectContaining({ edges }), expect.anything()),+ );+});++test('shows and removes implicit handoffs while retaining implicit fan-out direct edges', () => {+ const implicit: GraphEdge = { from: 'parent', to: 'child', prompt: 'Keep this' };+ const fanout: GraphEdge = { from: 'parent', to: ['left', 'right'] };+ render(<Harness edges={[fanout, implicit]} />);+ expect(screen.getAllByRole('button', { name: 'com_ui_agent_handoff_remove' })).toHaveLength(1);+ expect(mockGetValues('edges')).toEqual([fanout, implicit]);+ fireEvent.click(screen.getByRole('button', { name: 'com_ui_agent_handoff_remove' }));+ expect(mockGetValues('edges')).toEqual([fanout]);+});diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsxindex 9bc726a286..4ad1e57853 100644--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/ItemDialog.tsx@@ -1,5 +1,7 @@+import { useState } from 'react';import { OGDialog, OGDialogContent } from '@librechat/client';import type { AgentItem } from '../items/types';+import { AgentPickerPortalContext } from '../../Advanced/AgentList';import ItemDialogHeader from './ItemDialogHeader';import ItemDialogBody from './ItemDialogBody';import { cn } from '~/utils';@@ -11,12 +13,16 @@ interface Props {}export default function ItemDialog({ item, agentId, onClose }: Props) {+ const [portalElement, setPortalElement] = useState<HTMLDivElement | null>(null);+ const isOrchestration = item?.kind === 'builtin' && item.id === 'orchestration';const isAction = item?.kind === 'action';return (<OGDialog open={item !== null} onOpenChange={(next) => !next && onClose()}><OGDialogContent+ ref={setPortalElement}className={cn(- 'w-11/12 gap-0 overflow-hidden rounded-2xl p-0 md:max-h-[85dvh]',+ 'w-11/12 gap-0 rounded-2xl p-0 md:max-h-[85dvh]',+ isOrchestration ? 'overflow-visible' : 'overflow-hidden',isAction ? 'max-w-5xl' : 'max-w-[560px]',)}data-testid="item-dialog"@@ -26,13 +32,15 @@ export default function ItemDialog({ item, agentId, onClose }: Props) {<ItemDialogHeader item={item} /><divclassName={cn(- 'px-6 pb-6 pt-2',+ 'px-6 pt-2 pb-6',isAction? 'flex min-h-0 flex-1 flex-col overflow-hidden': 'flex-1 overflow-y-auto',)}>- <ItemDialogBody item={item} agentId={agentId} onClose={onClose} />+ <AgentPickerPortalContext.Provider value={portalElement}>+ <ItemDialogBody item={item} agentId={agentId} onClose={onClose} />+ </AgentPickerPortalContext.Provider></div></div>)}diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ItemDialog.spec.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ItemDialog.spec.tsxindex 65687f2d5d..114134f9d8 100644--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ItemDialog.spec.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/__tests__/ItemDialog.spec.tsx@@ -40,8 +40,10 @@ jest.mock('@librechat/client', () => {),): null,- OGDialogContent: ({ children, ...rest }: { children: React.ReactNode }) =>- React.createElement('div', rest, children),+ OGDialogContent: React.forwardRef(+ ({ children, ...rest }: { children: React.ReactNode }, ref: React.Ref<HTMLDivElement>) =>+ React.createElement('div', { ...rest, ref }, children),+ ),OGDialogHeader: ({ children, ...rest }: { children: React.ReactNode }) =>React.createElement('div', rest, children),OGDialogTitle: ({ children, ...rest }: { children: React.ReactNode }) =>diff --git a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsxindex 5e0a4a7a99..e0ee7c2af8 100644--- a/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ItemDialog/sections/BuiltinSection.tsx@@ -4,6 +4,7 @@ import { Tools, MemoryScope, ArtifactModes, AgentCapabilities } from 'librechat-import type { TranslationKeys } from '~/hooks/useLocalize';import type { AgentForm, ExtendedFile } from '~/common';import type { BuiltinId } from '../../items/types';+import OrchestrationHub from '../../../Advanced/OrchestrationHub';import { useVerifyAgentToolAuth } from '~/data-provider';import CodeBackground from '../../../Code/Background';import CodeSettings from '../../../Code/Settings';@@ -142,7 +143,9 @@ export default function BuiltinSection({let body: React.ReactNode = null;- if (builtinId === 'execute_code') {+ if (builtinId === 'orchestration') {+ body = <OrchestrationHub currentAgentId={agentId} />;+ } else if (builtinId === 'execute_code') {body = (<div className="flex flex-col gap-4"><CodeSettings />@@ -172,7 +175,8 @@ export default function BuiltinSection({);}- const localizedDescription = description ? localize(description as TranslationKeys) : '';+ const localizedDescription =+ description && builtinId !== 'orchestration' ? localize(description as TranslationKeys) : '';return (<div className="flex flex-col gap-5">diff --git a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsxindex 6db685769a..657efb4719 100644--- a/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ToolsMarketplaceDialog.tsx@@ -25,6 +25,7 @@ import { useAgentFileEntries, useAgentItems, useUninstallToolCredentials } fromimport MarketplaceSidebar, { MarketplaceFilterBar } from './MarketplaceSidebar';import { requiresFileManagerRemoval } from './items/capabilities';import AddMcpServerDialog from './ItemDialog/AddMcpServerDialog';+import { removeOrchestration } from './items/orchestration';import { computeToggleAction } from './items/mutations';import { useLocalize, useToolFavorites } from '~/hooks';import MarketplaceCatalog from './MarketplaceCatalog';@@ -127,6 +128,17 @@ export default function ToolsMarketplaceDialog({}const patch = computeToggleAction(item, { selected });switch (patch.type) {+ case 'configure':+ setDetailItem(item);+ break;+ case 'orchestration-remove': {+ const next = removeOrchestration(getValues('subagents'), getValues('edges'));+ if (next.subagents) {+ setValue('subagents', next.subagents, { shouldDirty: true });+ }+ setValue('edges', next.edges, { shouldDirty: true });+ break;+ }case 'builtin':setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });if (patch.field === AgentCapabilities.execute_code && patch.value === false) {@@ -228,7 +240,7 @@ export default function ToolsMarketplaceDialog({space below the catalog on a tall screen. Below md the shell is thefull-bleed sheet and the body is capped to the same 100dvh, because its`h-full` resolves against a grid area sized to the whole catalog. */}- <OGDialogContent className="h-[100dvh] max-h-[100dvh] w-full max-w-full overflow-hidden rounded-none border-border-medium p-0 shadow-xl md:h-auto md:max-h-[92vh] md:w-11/12 md:max-w-[1200px] md:rounded-2xl">+ <OGDialogContent className="border-border-medium h-[100dvh] max-h-[100dvh] w-full max-w-full overflow-hidden rounded-none p-0 shadow-xl md:h-auto md:max-h-[92vh] md:w-11/12 md:max-w-[1200px] md:rounded-2xl"><OGDialogTitle className="sr-only">{localize('com_ui_tools_marketplace')}</OGDialogTitle><OGDialogDescription className="sr-only">{localize('com_ui_tools_marketplace_description')}@@ -254,7 +266,7 @@ export default function ToolsMarketplaceDialog({<div className="flex items-center gap-2 px-4 py-3 pr-12 md:py-4 md:pl-6"><div className="relative flex-1"><Search- className="pointer-events-none absolute left-3 top-1/2 z-[1] size-4 -translate-y-1/2 text-text-tertiary"+ className="text-text-tertiary pointer-events-none absolute top-1/2 left-3 z-[1] size-4 -translate-y-1/2"aria-hidden="true"/><Inputdiff --git a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsxindex 7a0b07546b..8df2f31ba9 100644--- a/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx+++ b/client/src/components/SidePanel/Agents/Tools/ToolsSection.tsx@@ -24,6 +24,7 @@ import { useSkillsInfiniteQuery, useDeleteAgentAction } from '~/data-provider';import { requiresFileManagerRemoval } from './items/capabilities';import { useRemoveMCPTool, useVisibleTools } from '~/hooks/MCP';import ToolsMarketplaceDialog from './ToolsMarketplaceDialog';+import { removeOrchestration } from './items/orchestration';import { computeToggleAction } from './items/mutations';import { useLocalize, useHasAccess } from '~/hooks';import { useAgentPanelContext } from '~/Providers';@@ -124,6 +125,17 @@ export default function ToolsSection({ agentId }: Props) {}const patch = computeToggleAction(item, { selected: true });switch (patch.type) {+ case 'configure':+ setDialogItem(item);+ break;+ case 'orchestration-remove': {+ const next = removeOrchestration(getValues('subagents'), getValues('edges'));+ if (next.subagents) {+ setValue('subagents', next.subagents, { shouldDirty: true });+ }+ setValue('edges', next.edges, { shouldDirty: true });+ break;+ }case 'builtin':setValue(patch.field as keyof AgentForm, patch.value as never, { shouldDirty: true });if (patch.field === AgentCapabilities.execute_code && patch.value === false) {diff --git a/client/src/components/SidePanel/Agents/Tools/hooks.ts b/client/src/components/SidePanel/Agents/Tools/hooks.tsindex ad78248132..07dd80b140 100644--- a/client/src/components/SidePanel/Agents/Tools/hooks.ts+++ b/client/src/components/SidePanel/Agents/Tools/hooks.ts@@ -179,6 +179,8 @@ export function useAgentItems({const webSearchUserProvided = useWebSearchUserProvided();const builtinAuthMap = useBuiltinAuthMap();+ const subagents = useWatch({ control, name: 'subagents' });+ const edges = useWatch({ control, name: 'edges' });const toolsField = useWatch({ control, name: 'tools' });const skillsWatch = useWatch({ control, name: 'skills' });const tools = useMemo(() => (toolsField ?? []) as string[], [toolsField]);@@ -235,6 +237,8 @@ export function useAgentItems({() =>deriveSelectedItems({+ subagents,+ edges,execute_code: executeCode,web_search: webSearch,file_search: fileSearch,@@ -250,6 +254,8 @@ export function useAgentItems({agentActions,),[+ subagents,+ edges,executeCode,webSearch,fileSearch,diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.tsindex 94c0945bc2..b3d57ff719 100644--- a/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/catalog.spec.ts@@ -23,8 +23,8 @@ const askInputs: BuildCatalogInputs = {};describe('buildCatalog', () => {- test('returns empty when nothing is enabled', () => {- expect(buildCatalog(emptyInputs)).toEqual([]);+ test('offers orchestration for always-available handoffs without the subagents capability', () => {+ expect(buildCatalog(emptyInputs).map((item) => item.id)).toEqual(['orchestration']);});test('emits built-in items only for capabilities the admin enabled', () => {@@ -35,11 +35,20 @@ describe('buildCatalog', () => {},});expect(items.filter((i) => i.kind === 'builtin').map((i) => i.id)).toEqual([+ 'orchestration',AgentCapabilities.execute_code,AgentCapabilities.web_search,]);});+ test('offers exactly one orchestration item when subagents are enabled', () => {+ const items = buildCatalog({+ ...emptyInputs,+ agentsConfig: { capabilities: [AgentCapabilities.subagents] },+ });+ expect(items.map((item) => item.id)).toEqual(['orchestration']);+ });+test('emits the memory builtin only when showMemory is set', () => {const memoryId = (i: { kind: string; id: string }) =>i.kind === 'builtin' && i.id === AgentCapabilities.memory;@@ -203,7 +212,9 @@ describe('buildCatalog', () => {agentsConfig: { capabilities: [AgentCapabilities.web_search] },builtinAuthMap: new Map([[AgentCapabilities.web_search, true]]),});- const builtin = items.find((i) => i.kind === 'builtin');+ const builtin = items.find(+ (i) => i.kind === 'builtin' && i.id === AgentCapabilities.web_search,+ );expect(builtin?.status).toBe('needs_setup');});@@ -297,6 +308,13 @@ describe('buildCatalog', () => {makeAction({ action_id: 'a1', metadata: { domain: 'd' }, settings: { paths: {} } }),],});- expect(items.map((i) => i.kind)).toEqual(['builtin', 'mcp', 'tool', 'skill', 'action']);+ expect(items.map((i) => i.kind)).toEqual([+ 'builtin',+ 'builtin',+ 'mcp',+ 'tool',+ 'skill',+ 'action',+ ]);});});diff --git a/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.tsnew file mode 100644index 0000000000..ff83f2a477--- /dev/null+++ b/client/src/components/SidePanel/Agents/Tools/items/__tests__/orchestration.spec.ts@@ -0,0 +1,97 @@+import type { AgentSubagentsConfig, GraphEdge } from 'librechat-data-provider';+import type { FormSelection } from '../selectors';+import type { AgentItem } from '../types';+import { isHandoffEdge, removeOrchestration } from '../orchestration';+import { hasConfigurableSettings } from '../configurable';+import { deriveSelectedItems } from '../selectors';+import { computeToggleAction } from '../mutations';++const item: AgentItem = {+ kind: 'builtin',+ id: 'orchestration',+ name: '',+ description: '',+ iconKey: 'orchestration',+};+const form: FormSelection = {+ execute_code: false,+ web_search: false,+ file_search: false,+ memory: false,+ artifacts: '',+ tools: [],+ skills: [],+ context_files: [],+ knowledge_files: [],+ code_files: [],+};+const handoff: GraphEdge = {+ from: 'parent',+ to: 'child',+ edgeType: 'handoff',+ prompt: 'Keep this',+};+const direct: GraphEdge = { from: 'parent', to: 'other', edgeType: 'direct' };++test('derives the native item from existing subagent and handoff configurations', () => {+ expect(deriveSelectedItems(form, [item], [])).toEqual([]);+ expect(deriveSelectedItems({ ...form, subagents: { enabled: true } }, [item], [])).toEqual([+ item,+ ]);+ expect(deriveSelectedItems({ ...form, edges: [handoff] }, [item], [])).toEqual([item]);+ expect(+ deriveSelectedItems(+ { ...form, edges: [direct], subagents: { enabled: false, agent_ids: ['child'] } },+ [item],+ [],+ ),+ ).toEqual([]);+});++test('adding opens settings instead of writing a bogus capability or plugin', () => {+ expect(computeToggleAction(item, { selected: false })).toEqual({ type: 'configure' });+ expect(computeToggleAction(item, { selected: true })).toEqual({ type: 'orchestration-remove' });+ expect(hasConfigurableSettings(item)).toBe(true);+});++test('removal explicitly disables subagents and preserves their settings and unrelated edges', () => {+ const subagents: AgentSubagentsConfig = {+ enabled: true,+ allowSelf: false,+ agent_ids: ['child'],+ shareFiles: true,+ graphs: [+ {+ type: 'team',+ name: 'Review',+ description: 'Review work',+ entry_agent_id: 'child',+ result_agent_id: 'child',+ agent_ids: ['child'],+ edges: [],+ },+ ],+ };+ expect(removeOrchestration(subagents, [handoff, direct])).toEqual({+ subagents: { ...subagents, enabled: false },+ edges: [direct],+ });+ expect(subagents.enabled).toBe(true);+ expect(removeOrchestration(undefined, [handoff])).toEqual({ subagents: undefined, edges: [] });+});++test.each<[GraphEdge, boolean]>([+ [{ from: 'parent', to: 'child' }, true],+ [{ from: ['parent'], to: ['child'] }, true],+ [{ from: ['left', 'right'], to: 'child' }, true],+ [{ from: 'parent', to: ['left', 'right'] }, false],+ [{ from: 'parent', to: ['left', 'right'], condition: () => true }, true],+ [{ from: 'parent', to: ['left', 'right'], edgeType: 'handoff' }, true],+ [{ from: 'parent', to: 'child', edgeType: 'direct' }, false],+])('matches runtime classification for %j', (edge, expected) => {+ expect(isHandoffEdge(edge)).toBe(expected);+ expect(deriveSelectedItems({ ...form, edges: [edge] }, [item], [])).toEqual(+ expected ? [item] : [],+ );+ expect(removeOrchestration(undefined, [edge]).edges).toEqual(expected ? [] : [edge]);+});diff --git a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts b/client/src/components/SidePanel/Agents/Tools/items/catalog.tsindex 6080c9c31e..e7b5c633ac 100644--- a/client/src/components/SidePanel/Agents/Tools/items/catalog.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/catalog.ts@@ -119,7 +119,15 @@ function countEndpoints(settings: Action['settings']): number {}export function buildCatalog(inputs: BuildCatalogInputs): AgentItem[] {- const items: AgentItem[] = [];+ const items: AgentItem[] = [+ {+ kind: 'builtin',+ id: 'orchestration',+ iconKey: 'orchestration',+ name: 'com_ui_agent_orchestration',+ description: 'com_ui_agent_orchestration_hint',+ },+ ];const enabled = new Set(inputs.agentsConfig.capabilities);for (const def of BUILTIN_DEFINITIONS) {diff --git a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts b/client/src/components/SidePanel/Agents/Tools/items/configurable.tsindex cc63ac7f80..b3e4f6a7a6 100644--- a/client/src/components/SidePanel/Agents/Tools/items/configurable.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/configurable.ts@@ -16,6 +16,7 @@ export function hasConfigurableSettings(item: AgentItem): boolean {item.id === 'file_search' ||item.id === 'context' ||item.id === 'memory' ||+ item.id === 'orchestration' ||(item.id === 'web_search' && item.userProvidedAuth === true));case 'tool':diff --git a/client/src/components/SidePanel/Agents/Tools/items/icons.ts b/client/src/components/SidePanel/Agents/Tools/items/icons.tsindex 94827096fc..1e75d7049e 100644--- a/client/src/components/SidePanel/Agents/Tools/items/icons.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/icons.ts@@ -11,6 +11,7 @@ import {Workflow,Zap,Layers,+ Network,} from 'lucide-react';import type { LucideIcon } from 'lucide-react';import type { AgentItem } from './types';@@ -22,6 +23,10 @@ export interface ItemIcon {}const BUILTIN_ICONS: Record<string, ItemIcon> = {+ orchestration: {+ Icon: Network,+ colorClass: 'bg-series-2/15 text-series-2',+ },execute_code: {Icon: Code,colorClass: 'bg-series-7/15 text-series-7',diff --git a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts b/client/src/components/SidePanel/Agents/Tools/items/mutations.tsindex b20002b00d..e79206f84d 100644--- a/client/src/components/SidePanel/Agents/Tools/items/mutations.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/mutations.ts@@ -3,6 +3,8 @@ import type { AgentItem } from './types';export type TogglePatch =| { type: 'builtin'; field: AgentCapabilities; value: boolean | string }+ | { type: 'orchestration-remove' }+ | { type: 'configure' }| { type: 'tool-add'; id: string }| { type: 'tool-remove'; id: string }| { type: 'skill-add'; id: string }@@ -13,6 +15,9 @@ export type TogglePatch =| { type: 'action-remove'; actionId: string };function builtinTogglePatch(id: string, selected: boolean): TogglePatch {+ if (id === 'orchestration') {+ return selected ? { type: 'orchestration-remove' } : { type: 'configure' };+ }if (id === 'ask_user_question') {// Native tool presented as a builtin — it has no capability field; the// toggle edits agent.tools exactly like a plugin.diff --git a/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts b/client/src/components/SidePanel/Agents/Tools/items/orchestration.tsnew file mode 100644index 0000000000..232d176be9--- /dev/null+++ b/client/src/components/SidePanel/Agents/Tools/items/orchestration.ts@@ -0,0 +1,18 @@+import type { AgentSubagentsConfig, GraphEdge } from 'librechat-data-provider';++/** Match the SDK: untyped, unconditional one-to-many edges default to direct. */+export function isHandoffEdge(edge: GraphEdge): boolean {+ const sourceCount = Array.isArray(edge.from) ? edge.from.length : 1;+ const destinationCount = Array.isArray(edge.to) ? edge.to.length : 1;+ const defaultDirect =+ edge.edgeType == null && edge.condition == null && sourceCount === 1 && destinationCount > 1;+ return edge.edgeType !== 'direct' && !defaultDirect;+}++/** Disable orchestration without losing subagent settings or non-handoff edges. */+export function removeOrchestration(subagents?: AgentSubagentsConfig, edges?: GraphEdge[]) {+ return {+ subagents: subagents ? { ...subagents, enabled: false } : undefined,+ edges: (edges ?? []).filter((edge) => !isHandoffEdge(edge)),+ };+}diff --git a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts b/client/src/components/SidePanel/Agents/Tools/items/selectors.tsindex 9169bc9811..d1186e095f 100644--- a/client/src/components/SidePanel/Agents/Tools/items/selectors.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/selectors.ts@@ -4,11 +4,14 @@ import {normalizeServerName,buildServerNameAliases,} from 'librechat-data-provider';-import type { Action } from 'librechat-data-provider';+import type { Action, AgentSubagentsConfig, GraphEdge } from 'librechat-data-provider';import type { AgentItem, AgentItemKind } from './types';import { isFileBackedCapabilityEnabled } from './capabilities';+import { isHandoffEdge } from './orchestration';export interface FormSelection {+ subagents?: AgentSubagentsConfig;+ edges?: GraphEdge[];execute_code: boolean;web_search: boolean;file_search: boolean;@@ -50,6 +53,8 @@ function isBuiltinSelected(item: AgentItem, form: FormSelection): boolean {return Boolean(form.artifacts);case 'context':return form.context_files.length > 0;+ case 'orchestration':+ return form.subagents?.enabled === true || form.edges?.some(isHandoffEdge) === true;case 'ask_user_question':// Native tool presented as a builtin — selection lives in agent.tools.return form.tools.includes('ask_user_question');diff --git a/client/src/components/SidePanel/Agents/Tools/items/types.ts b/client/src/components/SidePanel/Agents/Tools/items/types.tsindex 5e27d33877..7478c15064 100644--- a/client/src/components/SidePanel/Agents/Tools/items/types.ts+++ b/client/src/components/SidePanel/Agents/Tools/items/types.ts@@ -21,7 +21,8 @@ export type BuiltinId =* toggling ride `agent.tools` exactly like a plugin — see the special cases* in `selectors.ts` / `mutations.ts`.*/- | 'ask_user_question';+ | 'ask_user_question'+ | 'orchestration';export type AgentItemStatus = 'needs_setup';diff --git a/e2e/specs/mock/agent-handoffs.spec.ts b/e2e/specs/mock/agent-handoffs.spec.tsindex 00ac352a6c..a4c13f83f8 100644--- a/e2e/specs/mock/agent-handoffs.spec.ts+++ b/e2e/specs/mock/agent-handoffs.spec.ts@@ -65,6 +65,41 @@ async function waitForMCPTool(page: Page, token: string): Promise<void> {).toEqual(expect.arrayContaining([expect.objectContaining({ pluginKey: MCP_TOOL_ID })]));}+async function openOrchestration(page: Page, form: Locator) {+ const settings = form+ .getByRole('listitem')+ .filter({ hasText: 'Multi-agent orchestration' })+ .getByRole('button', { name: 'Configure', exact: true });+ if (await settings.count()) {+ await settings.click();+ } else {+ await form.getByRole('button', { name: 'Add tools' }).click();+ await page+ .getByRole('dialog', { name: 'Tool Library', exact: true })+ .getByRole('listitem')+ .filter({ hasText: 'Multi-agent orchestration' })+ .getByRole('button', { name: 'Configure', exact: true })+ .click();+ }+ return page.getByTestId('item-dialog').getByRole('region', { name: 'Handoffs' });+}++async function closeOrchestration(page: Page) {+ if (!(await page.getByTestId('item-dialog').count())) {+ return;+ }+ await page.getByTestId('item-dialog').getByRole('button', { name: 'Close', exact: true }).click();+ await expect(page.getByTestId('item-dialog')).toBeHidden();+ const marketplace = page.getByRole('dialog', {+ name: 'Tool Library',+ exact: true,+ includeHidden: true,+ });+ if (await marketplace.count()) {+ await marketplace.getByRole('button', { name: 'Close', exact: true }).click();+ }+}+async function startNewAgent(page: Page): Promise<Locator> {let form = await openAgentBuilder(page);const createNewButton = form.getByRole('button', { name: 'Create New Agent' });@@ -89,6 +124,7 @@ async function configureNewAgent(page: Page, name: string): Promise<Locator> {async function createConfiguredAgent(form: Locator): Promise<AgentDetail> {const page = form.page();+ await closeOrchestration(page);const [response] = await Promise.all([page.waitForResponse((candidate) =>@@ -176,11 +212,12 @@ test.describe('agent handoffs', () => {bareSpecialistId = bareSpecialist.id;const routerForm = await configureNewAgent(page, routerName);- await routerForm.getByRole('button', { name: 'Advanced' }).click();- const handoffs = routerForm.getByRole('region', { name: 'Handoffs' });+ const handoffs = await openOrchestration(page, routerForm);await expect(handoffs).toBeVisible();await handoffs.getByRole('combobox', { name: 'Add agent' }).click();+ await page.locator('input[placeholder="Search agent"]:visible').fill(specialistName);+ await expect(page.locator('input[placeholder="Search agent"]:visible')).toBeFocused();await page.getByRole('option', { name: specialistName }).click();await expect(handoffs.getByText('1 / 10', { exact: true })).toBeVisible();await handoffs.getByRole('button', { name: 'Expand' }).click();@@ -222,8 +259,7 @@ test.describe('agent handoffs', () => {const reopenedForm = await openAgentBuilder(page);await reopenedForm.getByRole('combobox', { name: 'Agent', exact: true }).click();await page.getByRole('option', { name: routerName }).click();- await reopenedForm.getByRole('button', { name: 'Advanced' }).click();- const reopenedHandoffs = reopenedForm.getByRole('region', { name: 'Handoffs' });+ const reopenedHandoffs = await openOrchestration(page, reopenedForm);await expect(reopenedHandoffs.getByText('2 / 10', { exact: true })).toBeVisible();const reopenedDestinations = reopenedHandoffs.getByRole('combobox', {name: 'Select agent',@@ -240,6 +276,7 @@ test.describe('agent handoffs', () => {reopenedHandoffs.getByLabel("Content parameter name (default: 'instructions')"),).toHaveValue(HANDOFF_PROMPT_KEY);+ await closeOrchestration(page);await reopenedForm.getByRole('button', { name: 'Select Agent' }).click();await expect(page.getByRole('textbox', { name: 'Message input' })).toBeVisible();@@ -344,8 +381,7 @@ test.describe('agent handoffs', () => {createdIds.push(first.id, second.id, third.id);const routerForm = await configureNewAgent(page, routerName);- await routerForm.getByRole('button', { name: 'Advanced' }).click();- const handoffs = routerForm.getByRole('region', { name: 'Handoffs' });+ const handoffs = await openOrchestration(page, routerForm);const addAgent = handoffs.getByRole('combobox', { name: 'Add agent' });await addAgent.click();@@ -375,6 +411,8 @@ test.describe('agent handoffs', () => {const destinationDialog = page.getByRole('dialog', { name: 'Select agent' }).last();await expect(destinationDialog.getByRole('option', { name: firstName })).toBeVisible();await expect(destinationDialog.getByRole('option', { name: thirdName })).toBeVisible();+ await destinationDialog.getByPlaceholder('Search agent').fill(firstName);+ await expect(destinationDialog.getByPlaceholder('Search agent')).toBeFocused();await destinationDialog.getByRole('option', { name: firstName }).click();await addAgent.click();@@ -408,9 +446,7 @@ test.describe('agent handoffs', () => {await editForm.getByRole('combobox', { name: 'Agent', exact: true }).click();await page.getByRole('option', { name: routerName }).click();await expect(editForm.getByLabel('Agent name')).toHaveValue(routerName);- await editForm.getByRole('button', { name: 'Advanced' }).click();-- let editableHandoffs = editForm.getByRole('region', { name: 'Handoffs' });+ let editableHandoffs = await openOrchestration(page, editForm);await expect(editableHandoffs.getByText('2 / 10', { exact: true })).toBeVisible();await editableHandoffs.getByRole('button', { name: 'Expand' }).first().click();await editableHandoffs@@ -426,7 +462,7 @@ test.describe('agent handoffs', () => {.getByRole('option', { name: secondName }).click();- await editForm.getByRole('button', { name: 'Back to builder' }).click();+ await closeOrchestration(page);const [updateResponse] = await Promise.all([page.waitForResponse((response) =>@@ -461,8 +497,7 @@ test.describe('agent handoffs', () => {editForm = await openAgentBuilder(page);await editForm.getByRole('combobox', { name: 'Agent', exact: true }).click();await page.getByRole('option', { name: routerName }).click();- await editForm.getByRole('button', { name: 'Advanced' }).click();- editableHandoffs = editForm.getByRole('region', { name: 'Handoffs' });+ editableHandoffs = await openOrchestration(page, editForm);await expect(editableHandoffs.getByText('2 / 10', { exact: true })).toBeVisible();await expect(editableHandoffs.getByRole('combobox', { name: 'Select agent' }).first(),@@ -475,7 +510,7 @@ test.describe('agent handoffs', () => {'The updated persisted handoff',);- await editForm.getByRole('button', { name: 'Back to builder' }).click();+ await closeOrchestration(page);await editForm.getByRole('button', { name: 'Version', exact: true }).click();await expect(page.getByRole('heading', { name: 'Version History' })).toBeVisible();const history = page.getByRole('list', { name: 'Version History' });@@ -504,8 +539,7 @@ test.describe('agent handoffs', () => {await page.getByRole('button', { name: 'Back to builder' }).click();editForm = page.getByRole('form', { name: 'Agent configuration form' });- await editForm.getByRole('button', { name: 'Advanced' }).click();- editableHandoffs = editForm.getByRole('region', { name: 'Handoffs' });+ editableHandoffs = await openOrchestration(page, editForm);await expect(editableHandoffs.getByRole('combobox', { name: 'Select agent' }).first(),).toContainText(firstName);@@ -541,8 +575,7 @@ test.describe('agent handoffs', () => {}const routerForm = await configureNewAgent(page, uniqueAgentName('E2E Handoff Limit Router'));- await routerForm.getByRole('button', { name: 'Advanced' }).click();- const handoffs = routerForm.getByRole('region', { name: 'Handoffs' });+ const handoffs = await openOrchestration(page, routerForm);for (const targetName of targetNames) {await handoffs.getByRole('combobox', { name: 'Add agent' }).click();@@ -584,12 +617,10 @@ test.describe('agent handoffs', () => {let form = await openAgentBuilder(page);await form.getByRole('combobox', { name: 'Agent', exact: true }).click();await page.getByRole('option', { name: routerName }).click();- await form.getByRole('button', { name: 'Advanced' }).click();- await expect(- form.getByRole('region', { name: 'Handoffs' }).getByText('1 / 10', { exact: true }),- ).toBeVisible();+ const configuredHandoffs = await openOrchestration(page, form);+ await expect(configuredHandoffs.getByText('1 / 10', { exact: true })).toBeVisible();- await form.getByRole('button', { name: 'Back to builder' }).click();+ await closeOrchestration(page);await form.getByRole('combobox', { name: 'Agent', exact: true }).click();await page.getByRole('option', { name: targetName }).click();await expect(form.getByLabel('Agent name')).toHaveValue(targetName);@@ -610,8 +641,7 @@ test.describe('agent handoffs', () => {form = page.getByRole('form', { name: 'Agent configuration form' });await expect(form.getByLabel('Agent name')).toHaveValue(routerName, { timeout: 30000 });- await form.getByRole('button', { name: 'Advanced' }).click();- const handoffs = form.getByRole('region', { name: 'Handoffs' });+ const handoffs = await openOrchestration(page, form);await expect(handoffs.getByText('0 / 10', { exact: true })).toBeVisible({timeout: 30000,});diff --git a/packages/client/src/components/ControlCombobox.spec.tsx b/packages/client/src/components/ControlCombobox.spec.tsxindex 83dff63a9c..f055b0df09 100644--- a/packages/client/src/components/ControlCombobox.spec.tsx+++ b/packages/client/src/components/ControlCombobox.spec.tsx@@ -372,4 +372,35 @@ describe('ControlCombobox portal placement', () => {expect(screen.getByRole('option', { name: 'Option B' })).toBeInTheDocument();expect(screen.queryByRole('option', { name: 'Option A' })).not.toBeInTheDocument();});+ it('portals into the dialog outside a clipping scroll region', () => {+ function Harness() {+ const [container, setContainer] = useState<HTMLDivElement | null>(null);+ return (+ <OGDialog open>+ <OGDialogContent ref={setContainer}>+ <OGDialogTitle>Change project</OGDialogTitle>+ <div data-testid="scroller" className="overflow-auto">+ <ControlCombobox+ selectedValue="a"+ items={items}+ setValue={() => undefined}+ ariaLabel="Test combobox"+ searchPlaceholder="Search projects"+ isCollapsed={false}+ portalElement={container}+ />+ </div>+ </OGDialogContent>+ </OGDialog>+ );+ }+ render(<Harness />);+ openPopover();+ const search = screen.getByPlaceholderText('Search projects');+ expect(screen.getByRole('dialog', { name: 'Change project' }).contains(search)).toBe(true);+ expect(screen.getByTestId('scroller').contains(search)).toBe(false);+ fireEvent.change(search, { target: { value: 'Option B' } });+ expect(screen.getByRole('option', { name: 'Option B' })).toBeInTheDocument();+ expect(screen.queryByRole('option', { name: 'Option A' })).not.toBeInTheDocument();+ });});diff --git a/packages/client/src/components/ControlCombobox.tsx b/packages/client/src/components/ControlCombobox.tsxindex 6b1350b817..2d3820843b 100644--- a/packages/client/src/components/ControlCombobox.tsx+++ b/packages/client/src/components/ControlCombobox.tsx@@ -50,6 +50,8 @@ interface ControlComboboxProps {* the popover is not clipped.*/portal?: boolean;+ /** Keep portaled options inside a modal without clipping its scroll region. */+ portalElement?: Ariakit.SelectPopoverProps['portalElement'];/** Told when the popover opens and closes, for hosts that must behave* differently while it is up — e.g. a focus-trapped panel whose own Escape* handler must not fire while an open popover owns the key. */@@ -86,6 +88,7 @@ function ControlCombobox({variant = 'default',gutter = 4,portal = true,+ portalElement,onOpenChange,}: ControlComboboxProps): JSX.Element {const [searchValue, setSearchValue] = useState('');@@ -235,6 +238,7 @@ function ControlCombobox({store={select}gutter={gutter}portal={portal}+ portalElement={portalElement}className={cn('border-border-light bg-surface-secondary overflow-hidden rounded-xl border shadow-lg',popoverMaxHeight != null && 'flex flex-col',