The open-source agent harness - the runtime layer that turns an LLM into a working agent.
// @vitest-environment jsdom
import type { CatalogServer } from '@/server/types.js';
import { useExternalStoreRuntime, type ThreadMessageLike } from '@assistant-ui/react';
import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
import { beforeAll, describe, expect, it, vi } from 'vitest';
import { createMockAgentUIServer, createMockCatalog } from '../server/mockServer.js';
vi.mock('@truefoundry/trueforge-assistant-ui-runtime', () => ({
trueForgeAttachmentAdapter: {},
useTrueForgeAgentRuntime: () =>
useExternalStoreRuntime<ThreadMessageLike>({
messages: [],
isRunning: false,
convertMessage: (message: ThreadMessageLike) => message,
onNew: async () => {},
}),
useTrueForgeCancel: () => vi.fn(),
useTrueForgeToolResponses: () => ({ pending: [] }),
useTrueForgeApprovals: () => ({ pending: [] }),
useTrueForgeRespondToToolApproval: () => vi.fn(),
useTrueForgeMcpAuth: () => ({ pending: [], connect: vi.fn(), continue: vi.fn() }),
useTrueForgeHistoryPagination: () => ({
isLoadingMore: false,
hasMore: false,
loadMore: vi.fn(),
}),
useTrueForgeAgentSpec: () => ({
agentSpec: { model: { name: 'openai-main/gpt-4.1' } },
}),
useTrueForgeFlushAgentSpec: () => async () => {},
useTrueForgeAdoptAgentSpec: () => vi.fn(),
useTrueForgeUpdateAgentSpec: () => vi.fn(),
}));
vi.mock('thinking-orbs', () => ({
ThinkingOrb: () => <div data-testid="thinking-orb" />,
}));
vi.mock('@/atoms/monacoPreload.js', () => ({
preloadMonaco: vi.fn(() => Promise.resolve({ editor: {} })),
}));
vi.mock('@/plugins/trueforge-agent-server-adapter/index.js', () => ({
createTrueForgeAgentUIServer: vi.fn(async () =>
createMockAgentUIServer({
getCapabilities: async () => ({
data: {
sandbox: { enabled: true },
skill: { enabled: true },
settings: { enabled: true },
},
}),
}),
),
}));
import { AgentConfigInstructionsProvider } from '@/atoms/draft/AgentConfigInstructionsContext.js';
import type { UserAvatarProps } from '@/atoms/UserAvatar.js';
import { TrueForgeUI, type ChatLayout } from '@/containers/TrueForgeUI.js';
import { DrawerLayout } from '@/layouts/DrawerLayout.js';
import { SidebarLayout } from '@/layouts/SidebarLayout.js';
import { StackChatPanel } from '@/layouts/StackChatPanel.js';
import { WidgetLayout } from '@/layouts/WidgetLayout.js';
import { WidgetVisibilityProvider } from '@/layouts/WidgetVisibilityContext.js';
import { ServerProvider } from '@/server/ServerContext.js';
import { ShellModeProvider, useShellMode } from '@/server/ShellModeContext.js';
import { SlotsProvider } from '@/theme/SlotsProvider.js';
import { RuntimeHarness } from './RuntimeHarness.js';
function mockServer(catalog?: CatalogServer) {
return createMockAgentUIServer(catalog === undefined ? {} : { catalog });
}
function CustomUserAvatar({ labeled = false }: UserAvatarProps) {
return <div data-testid="custom-user-avatar">{labeled ? 'labeled user' : 'compact user'}</div>;
}
/** Minimal catalog stub — ShellActions only checks presence. */
const stubCatalog = createMockCatalog();
beforeAll(() => {
HTMLDialogElement.prototype.showModal = function showModal() {
this.setAttribute('open', '');
};
HTMLDialogElement.prototype.close = function close() {
this.removeAttribute('open');
this.dispatchEvent(new Event('close'));
};
});
function mobileMatchMedia(query: string): MediaQueryList {
return {
matches: query === '(max-width: 767px)',
media: query,
onchange: null,
addEventListener: vi.fn(),
removeEventListener: vi.fn(),
addListener: vi.fn(),
removeListener: vi.fn(),
dispatchEvent: vi.fn(() => true),
};
}
describe('TrueForgeUI', () => {
const server = mockServer();
const layouts: ChatLayout[] = ['sidebar', 'drawer', 'dock', 'widget'];
it.each(layouts)('mounts layout=%s without crashing', async layout => {
const { container } = render(
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={layout}
className="h-96"
/>,
);
await act(async () => {
await vi.dynamicImportSettled();
});
await waitFor(() => {
switch (layout) {
case 'sidebar':
expect(screen.getByRole('button', { name: 'Start new chat' })).toBeInTheDocument();
expect(screen.queryByRole('button', { name: /^(Collapse|Expand) sidebar$/ })).not.toBeInTheDocument();
break;
case 'drawer':
expect(screen.getByRole('button', { name: 'New Chat' })).toBeInTheDocument();
// SingleAgent has no composer — New Agent is composer-only.
expect(screen.queryByRole('button', { name: 'New Agent' })).not.toBeInTheDocument();
break;
case 'dock':
expect(container.querySelector('[data-aui-compact-layout]')).toBeInTheDocument();
break;
case 'widget':
expect(screen.getByRole('button', { name: 'Open chat' })).toBeInTheDocument();
break;
}
});
expect(container.querySelector('.h-96')).toBeInTheDocument();
});
it.each(layouts)('renders the current user in layout=%s chrome', async layout => {
render(
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={layout}
currentUser={{ displayName: 'Ada Lovelace' }}
className="h-96"
/>,
);
if (layout === 'widget') {
fireEvent.click(await screen.findByRole('button', { name: 'Open chat' }));
}
const avatar = await screen.findByLabelText('Ada Lovelace');
expect(avatar.querySelector('[data-slot="avatar-fallback"]')).toHaveTextContent(/^A$/);
expect(avatar).toHaveTextContent('Ada Lovelace');
if (layout === 'sidebar') {
expect(avatar.closest('aside')).not.toBeNull();
expect(avatar).toHaveClass('w-14.5');
} else if (layout === 'drawer') {
expect(avatar.closest('header')).not.toBeNull();
} else {
expect(avatar.closest('footer')).not.toBeNull();
}
});
it.each(layouts)('honors overrides.UserAvatar in layout=%s', async layout => {
render(
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={layout}
overrides={{ UserAvatar: CustomUserAvatar }}
className="h-96"
/>,
);
if (layout === 'widget') {
fireEvent.click(await screen.findByRole('button', { name: 'Open chat' }));
}
expect(await screen.findByTestId('custom-user-avatar')).toHaveTextContent(
layout === 'sidebar' ? 'labeled user' : 'compact user',
);
});
it('keeps the widget open across mutable runtime remounts', async () => {
render(
<TrueForgeUI server={mockServer()} agentConfig={{ mode: 'AgentComposer' }} layout="widget" className="h-96" />,
);
fireEvent.click(await screen.findByRole('button', { name: 'Open chat' }));
expect(screen.getByRole('dialog', { name: 'Chat' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'New Chat' }));
await waitFor(() => expect(screen.getByRole('dialog', { name: 'Chat' })).toBeInTheDocument());
fireEvent.click(screen.getByRole('button', { name: 'New Agent' }));
await waitFor(() => {
expect(screen.getByRole('dialog', { name: 'Chat' })).toBeInTheDocument();
expect(screen.getByRole('dialog', { name: 'Agent Config' })).toBeInTheDocument();
});
});
it('mounts a custom layout component inside providers', async () => {
function CustomLayout({ className }: { className?: string }) {
return (
<div data-testid="custom-layout" className={className}>
custom chrome
</div>
);
}
render(
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={CustomLayout}
className="h-96"
/>,
);
await waitFor(() => {
expect(screen.getByTestId('custom-layout')).toHaveTextContent('custom chrome');
});
});
it('keeps composer catalogs cached when starting a new chat', async () => {
const getCapabilities = vi
.fn()
.mockResolvedValueOnce({ data: { sandbox: { enabled: true }, skill: { enabled: true } } })
.mockResolvedValueOnce({
data: {
sandbox: { enabled: false },
skill: { enabled: false, reason: 'Select Sandbox first' },
},
});
const getModels = vi.fn(async () => []);
const getSkills = vi.fn(async () => []);
const getMcp = vi.fn(async () => []);
render(
<TrueForgeUI
server={createMockAgentUIServer({ getCapabilities, getModels, getSkills, getMcp })}
agentConfig={{ mode: 'AgentComposer' }}
layout="sidebar"
/>,
);
await waitFor(() => {
expect(getCapabilities).toHaveBeenCalledTimes(1);
expect(getModels).toHaveBeenCalledTimes(1);
expect(getSkills).toHaveBeenCalledTimes(1);
expect(getMcp).toHaveBeenCalledTimes(1);
});
fireEvent.click(screen.getByRole('button', { name: 'Start new chat' }));
await waitFor(() => {
expect(getCapabilities).toHaveBeenCalledTimes(2);
expect(getModels).toHaveBeenCalledTimes(1);
expect(getSkills).toHaveBeenCalledTimes(1);
expect(getMcp).toHaveBeenCalledTimes(1);
});
fireEvent.click(screen.getByRole('button', { name: 'Tools (0)' }));
fireEvent.click(screen.getByRole('button', { name: /Skills/ }));
expect(await screen.findByRole('status')).toHaveTextContent('Select Sandbox first');
});
it('keeps configuration editors out of Save Agent', async () => {
const getModels = vi.fn(async () => [
{
id: 'openai-main/gpt-4.1',
name: 'openai-main/gpt-4.1',
provider: { name: 'OpenAI' },
properties: {},
},
]);
const getMcp = vi.fn(async () => [{ id: 'github', name: 'GitHub', authenticated: true }]);
const getSkills = vi.fn(async () => [{ id: 'research', name: 'Research' }]);
render(
<TrueForgeUI
server={createMockAgentUIServer({ getModels, getMcp, getSkills })}
agentConfig={{ mode: 'AgentComposer' }}
layout="sidebar"
/>,
);
fireEvent.click(await screen.findByRole('button', { name: 'Start new agent' }));
fireEvent.click(await screen.findByRole('button', { name: 'Save Agent' }));
const saveDialog = await screen.findByRole('dialog', { name: 'Save agent' });
expect(within(saveDialog).getByLabelText('Agent name')).toBeInTheDocument();
expect(within(saveDialog).getByLabelText('Description')).toBeInTheDocument();
expect(within(saveDialog).queryByRole('button', { name: 'Edit Model' })).not.toBeInTheDocument();
expect(within(saveDialog).queryByRole('button', { name: 'Edit Connectors' })).not.toBeInTheDocument();
expect(getModels).toHaveBeenCalled();
expect(getMcp).toHaveBeenCalled();
expect(getSkills).toHaveBeenCalled();
});
it('renders only the MCP authorization screen when requested by the URL', async () => {
const originalUrl = window.location.href;
const postMessage = vi.fn();
const close = vi.fn();
vi.stubGlobal(
'BroadcastChannel',
class {
postMessage = postMessage;
close = close;
},
);
window.history.replaceState(null, '', '/?screenType=mcp-auth&pUid=popup-1&isSuccess=true');
let unmount: (() => void) | undefined;
try {
const view = render(
<TrueForgeUI
server={server}
agentConfig={{ mode: 'SingleAgent', name: 'my-agent' }}
layout={() => <div data-testid="regular-layout">regular chrome</div>}
/>,
);
unmount = view.unmount;
expect(await screen.findByText('Authorization successful')).toBeInTheDocument();
expect(screen.queryByTestId('regular-layout')).not.toBeInTheDocument();
} finally {
unmount?.();
window.history.replaceState(null, '', originalUrl);
vi.unstubAllGlobals();
}
});
it('resolves type trueforge and mounts the layout', async () => {
render(<TrueForgeUI server={{ type: 'trueforge', token: 'tok' }} layout="sidebar" className="h-96" />);
await waitFor(() => {
expect(screen.queryByRole('status', { name: 'Loading' })).not.toBeInTheDocument();
});
expect(screen.queryByRole('alert')).not.toBeInTheDocument();
});
});
describe('StackChatPanel', () => {
it('shows New Chat and New Agent actions on the thread header', () => {
render(
<SlotsProvider>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<StackChatPanel />
</div>
</RuntimeHarness>
</ShellModeProvider>
</SlotsProvider>,
);
expect(screen.getByRole('button', { name: 'New Chat' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'New Agent' })).toBeInTheDocument();
});
it.each([
['dock/widget', StackChatPanel],
['drawer', DrawerLayout],
] as const)('%s can return to chat after opening schedules', async (_name, Layout) => {
const server = createMockAgentUIServer({
schedules: {
listSchedules: vi.fn(async () => ({ data: [] })),
getSchedule: vi.fn(),
createSchedule: vi.fn(),
updateSchedule: vi.fn(),
deleteSchedule: vi.fn(),
listScheduleRuns: vi.fn(async () => []),
createScheduleRun: vi.fn(),
},
});
function OpenSchedules() {
const shell = useShellMode();
return (
<button type="button" onClick={() => shell.setSchedulesOpen(true)}>
Open schedules
</button>
);
}
render(
<SlotsProvider>
<ServerProvider server={server}>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
<RuntimeHarness messages={[]}>
<OpenSchedules />
<div className="h-96">
<Layout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(screen.getByRole('button', { name: 'Open schedules' }));
expect(await screen.findByRole('heading', { name: 'Agent Schedules' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Back to chat' }));
await waitFor(() => {
expect(screen.queryByRole('heading', { name: 'Agent Schedules' })).not.toBeInTheDocument();
});
});
});
describe('SidebarLayout', () => {
it('shows a desktop-only notice for Build Agent on mobile', () => {
const originalMatchMedia = window.matchMedia;
Object.defineProperty(window, 'matchMedia', { configurable: true, value: mobileMatchMedia });
try {
render(
<SlotsProvider>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider>
<AgentConfigInstructionsProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</AgentConfigInstructionsProvider>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
// Desktop rail is CSS-hidden but still mounted; click Build Agent from there.
fireEvent.click(screen.getByRole('button', { name: 'Start new agent' }));
expect(screen.getByRole('heading', { name: 'Best viewed on desktop' })).toBeInTheDocument();
expect(screen.queryByRole('dialog', { name: 'Agent Config' })).not.toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Navigation' })).toBeInTheDocument();
} finally {
Object.defineProperty(window, 'matchMedia', { configurable: true, value: originalMatchMedia });
}
});
it('opens a Claude-style mobile navigation drawer with history and footer actions', async () => {
render(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme', icon: { src: '/acme.svg' } } }}>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(screen.getByRole('button', { name: 'Navigation' }));
const drawer = screen.getByRole('dialog', { name: 'Navigation' });
expect(drawer).toHaveClass('w-80');
expect(within(drawer).getByAltText('Acme')).toHaveAttribute('src', '/acme.svg');
expect(within(drawer).getByText('Acme')).toBeInTheDocument();
expect(within(drawer).getByRole('button', { name: 'Close navigation' })).toBeInTheDocument();
expect(within(drawer).getByRole('button', { name: 'Start new chat' })).toBeInTheDocument();
expect(within(drawer).queryByRole('button', { name: 'Start new agent' })).not.toBeInTheDocument();
expect(within(drawer).queryByRole('button', { name: 'Sessions' })).not.toBeInTheDocument();
expect(within(drawer).queryByRole('button', { name: 'Schedules' })).not.toBeInTheDocument();
expect(within(drawer).getByRole('button', { name: /^Agents/ })).toBeInTheDocument();
expect(within(drawer).getByText('Chat History')).toBeInTheDocument();
expect(within(drawer).getByRole('link', { name: 'Documentation' })).toBeInTheDocument();
expect(within(drawer).getByRole('button', { name: /Switch to (light|dark) theme/ })).toBeInTheDocument();
expect(await within(drawer).findByRole('button', { name: 'Settings' })).toBeInTheDocument();
fireEvent.click(within(drawer).getByRole('button', { name: 'Close navigation' }));
expect(screen.queryByRole('dialog', { name: 'Navigation' })).not.toBeInTheDocument();
});
it('closes the mobile drawer on Escape, backdrop click, and New Chat', () => {
render(
<SlotsProvider>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
const menu = screen.getByRole('button', { name: 'Navigation' });
fireEvent.click(menu);
expect(screen.getByRole('dialog', { name: 'Navigation' })).toBeInTheDocument();
fireEvent.keyDown(window, { key: 'Escape' });
expect(screen.queryByRole('dialog', { name: 'Navigation' })).not.toBeInTheDocument();
expect(menu).toHaveFocus();
fireEvent.click(menu);
fireEvent.click(screen.getByRole('button', { name: 'Close navigation backdrop' }));
expect(screen.queryByRole('dialog', { name: 'Navigation' })).not.toBeInTheDocument();
fireEvent.click(menu);
fireEvent.click(
within(screen.getByRole('dialog', { name: 'Navigation' })).getByRole('button', { name: 'Start new chat' }),
);
expect(screen.queryByRole('dialog', { name: 'Navigation' })).not.toBeInTheDocument();
});
it('closes the mobile drawer on Escape without dismissing Settings underneath', async () => {
const originalMatchMedia = window.matchMedia;
Object.defineProperty(window, 'matchMedia', { configurable: true, value: mobileMatchMedia });
try {
render(
<SlotsProvider>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(await screen.findByRole('button', { name: 'Settings' }));
expect(await screen.findByRole('heading', { name: 'Settings' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Navigation' }));
expect(screen.getByRole('dialog', { name: 'Navigation' })).toBeInTheDocument();
fireEvent.keyDown(window, { key: 'Escape' });
expect(screen.queryByRole('dialog', { name: 'Navigation' })).not.toBeInTheDocument();
expect(screen.getByRole('heading', { name: 'Settings' })).toBeInTheDocument();
} finally {
Object.defineProperty(window, 'matchMedia', { configurable: true, value: originalMatchMedia });
}
});
it('inlines the hamburger into Settings and Agents headers on mobile', async () => {
const originalMatchMedia = window.matchMedia;
Object.defineProperty(window, 'matchMedia', { configurable: true, value: mobileMatchMedia });
try {
render(
<SlotsProvider>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(await screen.findByRole('button', { name: 'Settings' }));
const settingsHeading = await screen.findByRole('heading', { name: 'Settings' });
const settingsNav = screen.getByRole('button', { name: 'Navigation' });
expect(settingsHeading.previousElementSibling).toBe(settingsNav);
expect(screen.queryByRole('button', { name: 'Back' })).not.toBeInTheDocument();
fireEvent.click(settingsNav);
fireEvent.click(
within(screen.getByRole('dialog', { name: 'Navigation' })).getByRole('button', { name: /^Agents/ }),
);
const agentsHeading = await screen.findByRole('heading', { name: 'Agents' });
expect(agentsHeading.previousElementSibling).toBe(screen.getByRole('button', { name: 'Navigation' }));
} finally {
Object.defineProperty(window, 'matchMedia', { configurable: true, value: originalMatchMedia });
}
});
it('shows the default icon mark in the permanent rail', () => {
const { container } = render(
<SlotsProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</SlotsProvider>,
);
const mark = container.querySelector('aside svg');
expect(mark).toHaveAttribute('viewBox', '0 0 140 140');
expect(screen.queryByText('TrueForge')).not.toBeInTheDocument();
expect(screen.queryByRole('button', { name: /^(Collapse|Expand) sidebar$/ })).not.toBeInTheDocument();
});
it('uses the square brand icon in the rail (not the wide wordmark)', () => {
const { container } = render(
<SlotsProvider
theme={{ brand: { mode: 'logo', name: 'Acme', icon: '/acme-icon.svg', logo: '/acme-wordmark.svg' } }}
>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</SlotsProvider>,
);
expect(container.querySelector('aside img')).toHaveAttribute('src', '/acme-icon.svg');
expect(screen.queryByText('Acme')).not.toBeInTheDocument();
});
it('supports icon-only branding in the rail', () => {
const { container } = render(
<SlotsProvider theme={{ brand: { mode: 'icon-only', name: 'Acme', icon: '/acme-icon.svg' } }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</SlotsProvider>,
);
expect(container.querySelector('aside img')).toHaveAttribute('src', '/acme-icon.svg');
expect(container.querySelector('aside img')).toHaveAttribute('alt', 'Acme');
expect(screen.queryByText('Acme')).not.toBeInTheDocument();
});
it('shows a permanent labeled rail with New Chat and no expand control', () => {
const { container } = render(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme', icon: '/acme.svg' } }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</SlotsProvider>,
);
expect(container.querySelector('aside img')).toHaveAttribute('src', '/acme.svg');
expect(screen.queryByText('Acme')).not.toBeInTheDocument();
expect(screen.getByRole('button', { name: 'Start new chat' })).toBeInTheDocument();
expect(screen.getByText('New Chat')).toBeInTheDocument();
expect(screen.getByRole('link', { name: 'Documentation' })).toHaveAttribute('href', 'https://trueforge.dev');
expect(screen.queryByRole('button', { name: /^(Collapse|Expand) sidebar$/ })).not.toBeInTheDocument();
});
it('keeps recent history visible when a named chat loads in the same page', async () => {
function OpenNamedChatButton() {
const shell = useShellMode();
return (
<button type="button" onClick={() => shell.selectLibraryAgent({ isMutable: false, agentName: 'named-agent' })}>
Open named chat
</button>
);
}
render(
<SlotsProvider>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider>
<AgentConfigInstructionsProvider>
<RuntimeHarness messages={[]}>
<OpenNamedChatButton />
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</AgentConfigInstructionsProvider>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
const recentChats = screen.getByRole('complementary', { name: 'Recent chats' });
expect(recentChats).toHaveClass('hidden', 'md:flex');
expect(recentChats.parentElement?.previousElementSibling?.tagName).toBe('HEADER');
expect(screen.getAllByText('New Chat')).toHaveLength(2);
fireEvent.click(screen.getByRole('button', { name: 'Start new agent' }));
await waitFor(() => {
expect(screen.queryByRole('complementary', { name: 'Recent chats' })).not.toBeInTheDocument();
});
fireEvent.click(screen.getByRole('button', { name: 'Start new chat' }));
expect(await screen.findByRole('complementary', { name: 'Recent chats' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Open named chat' }));
expect(await screen.findByRole('complementary', { name: 'Recent chats' })).toBeInTheDocument();
});
it('highlights New Chat, New Agent, and Settings when selected', async () => {
function NamedAgentButtons() {
const shell = useShellMode();
return (
<>
<button type="button" onClick={() => shell.selectLibraryAgent({ isMutable: false, agentName: 'support' })}>
Open history
</button>
<button
type="button"
onClick={() => shell.selectLibraryAgent({ isMutable: false, agentId: 'support-id', agentName: 'support' })}
>
Try support
</button>
</>
);
}
render(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme' } }}>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider>
<AgentConfigInstructionsProvider>
<RuntimeHarness messages={[]}>
<NamedAgentButtons />
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</AgentConfigInstructionsProvider>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
const newChat = screen.getByRole('button', { name: 'Start new chat' });
const newAgent = screen.getByRole('button', { name: 'Start new agent' });
expect(newChat).toHaveAttribute('aria-current', 'page');
expect(newAgent).not.toHaveAttribute('aria-current');
fireEvent.click(screen.getByRole('button', { name: 'Open history' }));
expect(newChat).toHaveAttribute('aria-current', 'page');
expect(newAgent).not.toHaveAttribute('aria-current');
fireEvent.click(screen.getByRole('button', { name: 'Try support' }));
expect(newChat).not.toHaveAttribute('aria-current');
expect(newAgent).not.toHaveAttribute('aria-current');
fireEvent.click(newAgent);
const selectedNewAgent = await screen.findByRole('button', { name: 'Start new agent' });
const deselectedNewChat = screen.getByRole('button', { name: 'Start new chat' });
expect(selectedNewAgent).toHaveAttribute('aria-current', 'page');
expect(deselectedNewChat).not.toHaveAttribute('aria-current');
const config = await screen.findByRole('dialog', { name: 'Agent Config' });
const chatColumn = config.nextElementSibling;
expect(config).toHaveClass('md:max-w-140', 'md:flex-1', '2xl:max-w-150', 'border-r');
expect(chatColumn).not.toBeNull();
expect(config.querySelector('header')).toHaveClass('min-h-14');
expect(chatColumn?.querySelector('header')).toHaveClass('min-h-14');
expect(screen.queryByRole('button', { name: 'Agent config' })).not.toBeInTheDocument();
const [settingsButton] = await screen.findAllByRole('button', { name: 'Settings' });
if (settingsButton === undefined) {
throw new Error('Expected settings button');
}
expect(settingsButton).not.toHaveAttribute('aria-current');
fireEvent.click(settingsButton);
expect(await screen.findByRole('heading', { name: 'Settings' })).toBeInTheDocument();
expect(settingsButton).toHaveAttribute('aria-current', 'page');
expect(deselectedNewChat).not.toHaveAttribute('aria-current');
expect(selectedNewAgent).not.toHaveAttribute('aria-current');
});
it('toggles theme from the footer and shows settings only when catalog is provided', async () => {
const { rerender } = render(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme' } }}>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
expect(await screen.findAllByRole('button', { name: 'Settings' })).toHaveLength(1);
expect(await screen.findAllByRole('button', { name: 'Agents' })).not.toHaveLength(0);
const [themeButton] = screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ });
if (themeButton === undefined) {
throw new Error('Expected theme toggle');
}
fireEvent.click(themeButton);
expect(screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ })).toHaveLength(1);
// Settings stays available with a locked agentName when catalog is present.
rerender(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme' } }}>
<ServerProvider server={mockServer(stubCatalog)}>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'locked-agent' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
expect(await screen.findAllByRole('button', { name: 'Settings' })).toHaveLength(1);
const [settingsButton] = screen.getAllByRole('button', { name: 'Settings' });
if (settingsButton === undefined) {
throw new Error('Expected settings button');
}
fireEvent.click(settingsButton);
// SettingsBuilder is lazy-loaded behind Suspense in the layout.
expect(await screen.findByRole('heading', { name: 'Settings' })).toBeInTheDocument();
rerender(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme' } }}>
<ServerProvider
server={createMockAgentUIServer({
catalog: stubCatalog,
getCapabilities: async () => ({
data: {
sandbox: { enabled: true },
skill: { enabled: true },
settings: { enabled: false },
},
}),
})}
>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
await waitFor(() => {
expect(screen.queryByRole('button', { name: 'Settings' })).not.toBeInTheDocument();
expect(screen.queryByRole('heading', { name: 'Settings' })).not.toBeInTheDocument();
});
// No catalog → no Settings button.
rerender(
<SlotsProvider theme={{ brand: { mode: 'icon-title', name: 'Acme' } }}>
<ServerProvider server={mockServer()}>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<SidebarLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
expect(screen.queryByRole('button', { name: 'Settings' })).not.toBeInTheDocument();
expect(screen.getAllByRole('button', { name: /Switch to (light|dark) theme/ })).toHaveLength(1);
});
});
describe('DrawerLayout a11y', () => {
it('exposes New Chat and New Agent actions', () => {
render(
<SlotsProvider>
<ShellModeProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<DrawerLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</SlotsProvider>,
);
expect(screen.getByRole('button', { name: 'New Chat' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: 'New Agent' })).toBeInTheDocument();
});
it('shows Back to chat on the mobile desktop-only notice', () => {
const originalMatchMedia = window.matchMedia;
Object.defineProperty(window, 'matchMedia', { configurable: true, value: mobileMatchMedia });
const server = createMockAgentUIServer({
schedules: {
listSchedules: vi.fn(async () => ({ data: [] })),
getSchedule: vi.fn(),
createSchedule: vi.fn(),
updateSchedule: vi.fn(),
deleteSchedule: vi.fn(),
listScheduleRuns: vi.fn(async () => []),
createScheduleRun: vi.fn(),
},
});
function OpenSchedules() {
const shell = useShellMode();
return (
<button type="button" onClick={() => shell.setSchedulesOpen(true)}>
Open schedules
</button>
);
}
try {
render(
<SlotsProvider>
<ServerProvider server={server}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<RuntimeHarness messages={[]}>
<OpenSchedules />
<div className="h-96">
<DrawerLayout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(screen.getByRole('button', { name: 'Open schedules' }));
expect(screen.getByRole('heading', { name: 'Best viewed on desktop' })).toBeInTheDocument();
expect(screen.getByRole('button', { name: /Back to chat/i })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: /Back to chat/i }));
expect(screen.queryByRole('heading', { name: 'Best viewed on desktop' })).not.toBeInTheDocument();
} finally {
Object.defineProperty(window, 'matchMedia', { configurable: true, value: originalMatchMedia });
}
});
it('keeps the agent builder open when Back to chat dismisses Schedules on desktop', async () => {
const server = createMockAgentUIServer({
schedules: {
listSchedules: vi.fn(async () => ({ data: [] })),
getSchedule: vi.fn(),
createSchedule: vi.fn(),
updateSchedule: vi.fn(),
deleteSchedule: vi.fn(),
listScheduleRuns: vi.fn(async () => []),
createScheduleRun: vi.fn(),
},
});
function OpenSchedules() {
const shell = useShellMode();
return (
<button type="button" onClick={() => shell.setSchedulesOpen(true)}>
Open schedules
</button>
);
}
render(
<SlotsProvider>
<ServerProvider server={server}>
<ShellModeProvider agentConfig={{ mode: 'AgentLibraryWithComposer' }}>
<AgentConfigInstructionsProvider>
<RuntimeHarness messages={[]}>
<OpenSchedules />
<div className="h-96">
<DrawerLayout />
</div>
</RuntimeHarness>
</AgentConfigInstructionsProvider>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
fireEvent.click(screen.getByRole('button', { name: 'New Agent' }));
expect(await screen.findByRole('dialog', { name: 'Agent Config' })).toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: 'Open schedules' }));
expect(await screen.findByRole('heading', { name: 'Agent Schedules' })).toBeInTheDocument();
expect(screen.queryByRole('dialog', { name: 'Agent Config' })).not.toBeInTheDocument();
fireEvent.click(screen.getByRole('button', { name: /Back to chat/i }));
await waitFor(() => {
expect(screen.queryByRole('heading', { name: 'Agent Schedules' })).not.toBeInTheDocument();
});
expect(screen.getByRole('dialog', { name: 'Agent Config' })).toBeInTheDocument();
});
});
describe('layout slot overrides', () => {
function CustomClearChat() {
return <button type="button">custom clear</button>;
}
function CustomShareChat() {
return <button type="button">custom share</button>;
}
function CustomSaveAgent() {
return <button type="button">custom save</button>;
}
function CustomActionSlot() {
return <button type="button">custom action</button>;
}
// dock and widget render their header through StackChatPanel.
const hosts = [
['sidebar', SidebarLayout],
['drawer', DrawerLayout],
['dock/widget', StackChatPanel],
] as const;
it.each(hosts)('%s honors overrides.ClearChatButton', (_name, Layout) => {
render(
<SlotsProvider overrides={{ ClearChatButton: CustomClearChat }}>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<Layout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</SlotsProvider>,
);
expect(screen.getByRole('button', { name: 'custom clear' })).toBeInTheDocument();
});
it.each(hosts)('%s places Share, New Chat, and Save Agent in order', (_name, Layout) => {
render(
<SlotsProvider
overrides={{
ShareChatButton: CustomShareChat,
ClearChatButton: CustomClearChat,
SaveAgentButton: CustomSaveAgent,
}}
>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<Layout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</SlotsProvider>,
);
const shareChat = screen.getByRole('button', { name: 'custom share' });
const clearChat = screen.getByRole('button', { name: 'custom clear' });
const saveAgent = screen.getByRole('button', { name: 'custom save' });
expect(shareChat.nextElementSibling).toBe(clearChat);
expect(clearChat.nextElementSibling).toBe(saveAgent);
});
it.each(hosts)('%s honors overrides.ShellActionsActionSlot to the right of shell actions', (_name, Layout) => {
render(
<SlotsProvider overrides={{ ShellActionsActionSlot: CustomActionSlot }}>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<Layout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</SlotsProvider>,
);
expect(screen.getAllByRole('button', { name: 'custom action' }).length).toBeGreaterThan(0);
});
const settingsCatalog: CatalogServer = {
modelCatalog: {
getModelProviderCatalog: vi.fn(async () => []),
listModelProviders: vi.fn(async () => []),
createModelProvider: vi.fn(),
updateModelProvider: vi.fn(),
},
connectorCatalog: {
getConnectorCatalog: vi.fn(async () => []),
getConnector: vi.fn(),
listConnectors: vi.fn(async () => []),
getToolsByConnectorId: vi.fn(async () => []),
createConnector: vi.fn(),
updateConnector: vi.fn(),
authenticateConnector: vi.fn(),
disconnectConnector: vi.fn(),
},
};
it.each(hosts)(
'%s keeps ShellActionsActionSlot mounted when Settings opens (no remount handoff)',
async (_name, Layout) => {
render(
<SlotsProvider overrides={{ ShellActionsActionSlot: CustomActionSlot }}>
<ServerProvider server={mockServer(settingsCatalog)}>
<ShellModeProvider agentConfig={{ mode: 'SingleAgent', name: 'a' }}>
<RuntimeHarness messages={[]}>
<div className="h-96">
<Layout />
</div>
</RuntimeHarness>
</ShellModeProvider>
</ServerProvider>
</SlotsProvider>,
);
const before = screen.getAllByRole('button', { name: 'custom action' });
expect(before.length).toBeGreaterThan(0);
const beforeNode = before[0];
fireEvent.click((await screen.findAllByRole('button', { name: 'Settings' }))[0]!);
// SettingsBuilder is lazy-loaded behind Suspense in the layout.
expect(await screen.findByRole('heading', { name: 'Settings' })).toBeInTheDocument();
const after = screen.getAllByRole('button', { name: 'custom action' });
expect(after.length).toBeGreaterThan(0);
// Same DOM node — layout did not remount the host override on Settings toggle.
expect(after).toContain(beforeNode);
},
);
});
describe('WidgetLayout a11y', () => {
it('opens chat dialog, focuses it, and restores FAB focus on Escape', async () => {
render(
<SlotsProvider>
<WidgetVisibilityProvider>
<RuntimeHarness messages={[]}>
<div className="h-96">
<WidgetLayout />
</div>
</RuntimeHarness>
</WidgetVisibilityProvider>
</SlotsProvider>,
);
const fab = screen.getByRole('button', { name: 'Open chat' });
expect(fab).toHaveAttribute('aria-expanded', 'false');
fireEvent.click(fab);
const dialog = screen.getByRole('dialog', { name: 'Chat' });
expect(dialog).toBeInTheDocument();
await waitFor(() => {
expect(dialog).toHaveFocus();
});
expect(screen.getByRole('button', { name: 'Close chat' })).toHaveAttribute('aria-expanded', 'true');
fireEvent.keyDown(window, { key: 'Escape' });
expect(screen.queryByRole('dialog', { name: 'Chat' })).not.toBeInTheDocument();
const openFab = screen.getByRole('button', { name: 'Open chat' });
expect(openFab).toHaveAttribute('aria-expanded', 'false');
await waitFor(() => {
expect(openFab).toHaveFocus();
});
});
});