The open-source agent harness - the runtime layer that turns an LLM into a working agent.
feat: implement settings capability toggle in UI (#645)
Govinda Vashishtha54e4ec47c936
diff --git a/.changeset/gate-settings-capability.md b/.changeset/gate-settings-capability.mdnew file mode 100644index 000000000..310408968--- /dev/null+++ b/.changeset/gate-settings-capability.md@@ -0,0 +1,5 @@+---+'@truefoundry/trueforge-ui': patch+---++Keep Settings hidden until the server explicitly enables it.diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsxindex 2accfa75d..691fe4497 100644--- a/packages/frontend/src/App.tsx+++ b/packages/frontend/src/App.tsx@@ -96,7 +96,7 @@ export function App() {if (first === undefined) {setBoot({status: 'ready',- openSettings: true,+ openSettings: capabilities.settings.enabled,defaultAgentSpec: {model: { name: '' },config: sandboxConfig,diff --git a/packages/trueforge-ui/src/routing/ShellRouteSync.tsx b/packages/trueforge-ui/src/routing/ShellRouteSync.tsxindex 4ec0607c4..6e6a58f09 100644--- a/packages/trueforge-ui/src/routing/ShellRouteSync.tsx+++ b/packages/trueforge-ui/src/routing/ShellRouteSync.tsx@@ -10,6 +10,7 @@ import {useOptionalScheduleServer,useOptionalServer,useServerCapabilities,+ useServerCapabilitiesSettled,} from '../server/ServerContext.js';import { useShellMode } from '../server/ShellModeContext.js';import { toEffectiveRoutes } from '../server/serverChrome.js';@@ -36,6 +37,7 @@ export function ShellRouteSync({const sessions = useOptionalAgentSessionsServer();const schedules = useOptionalScheduleServer();const capabilities = useServerCapabilities();+ const capabilitiesSettled = useServerCapabilitiesSettled();const navigate = useNavigate();const location = useLocation();// Same gates as sidebar chrome: missing optional ports unregister their paths.@@ -164,6 +166,12 @@ export function ShellRouteSync({// sole authority for the first commit and sets the final URL + `prevPlaceRef`.useEffect(() => {if (bootedRef.current) return;+ const configuredUrlPlace = matchLocation({+ pathname: location.pathname,+ search: location.search,+ routes,+ });+ if (!capabilitiesSettled && configuredUrlPlace?.type === 'settings') return;bootedRef.current = true;const urlPlace = matchLocation({@@ -197,9 +205,9 @@ export function ShellRouteSync({selfNavPathRef.current = desiredPath !== location.pathname ? desiredPath : null;navigate({ pathname: desiredPath, search: desiredSearch, hash: location.hash }, { replace: true });}- // Boot runs once; snapshot is read imperatively here.+ // Boot runs once after any capability-dependent Settings destination resolves.// eslint-disable-next-line react-hooks/exhaustive-deps- }, []);+ }, [capabilitiesSettled]);// Shell -> URL: mirror the derived place. Skip the first commit (boot owns it).useEffect(() => {diff --git a/packages/trueforge-ui/src/server/ServerContext.tsx b/packages/trueforge-ui/src/server/ServerContext.tsxindex 8326e9440..eb0db4ceb 100644--- a/packages/trueforge-ui/src/server/ServerContext.tsx+++ b/packages/trueforge-ui/src/server/ServerContext.tsx@@ -14,11 +14,13 @@ import type {const ServerContext = createContext<AgentUIServer | null>(null);const ServerCapabilitiesContext = createContext<{capabilities: AgentBuilderCapabilitiesResponse['data'] | null;+ settled: boolean;refresh: () => void;} | null>(null);export function ServerProvider({ server, children }: { server: AgentUIServer; children: ReactNode }) {const [capabilities, setCapabilities] = useState<AgentBuilderCapabilitiesResponse['data'] | null>(null);+ const [capabilitiesSettled, setCapabilitiesSettled] = useState(false);const cancelActiveRequestRef = useRef<(() => void) | null>(null);const refreshCapabilities = useCallback(() => {cancelActiveRequestRef.current?.();@@ -33,11 +35,15 @@ export function ServerProvider({ server, children }: { server: AgentUIServer; ch}).catch(() => {// Preserve the last known capabilities when a refresh fails.+ })+ .finally(() => {+ if (!cancelled) setCapabilitiesSettled(true);});}, [server]);useEffect(() => {setCapabilities(null);+ setCapabilitiesSettled(false);refreshCapabilities();return () => {cancelActiveRequestRef.current?.();@@ -45,8 +51,8 @@ export function ServerProvider({ server, children }: { server: AgentUIServer; ch}, [refreshCapabilities]);const capabilitiesValue = useMemo(- () => ({ capabilities, refresh: refreshCapabilities }),- [capabilities, refreshCapabilities],+ () => ({ capabilities, settled: capabilitiesSettled, refresh: refreshCapabilities }),+ [capabilities, capabilitiesSettled, refreshCapabilities],);return (@@ -72,6 +78,10 @@ export function useServerCapabilities(): AgentBuilderCapabilitiesResponse['data'return useContext(ServerCapabilitiesContext)?.capabilities ?? null;}+export function useServerCapabilitiesSettled(): boolean {+ return useContext(ServerCapabilitiesContext)?.settled ?? false;+}+export function useOptionalRefreshServerCapabilities(): (() => void) | null {return useContext(ServerCapabilitiesContext)?.refresh ?? null;}diff --git a/packages/trueforge-ui/src/server/ShellModeContext.tsx b/packages/trueforge-ui/src/server/ShellModeContext.tsxindex 03657e24b..9367ba531 100644--- a/packages/trueforge-ui/src/server/ShellModeContext.tsx+++ b/packages/trueforge-ui/src/server/ShellModeContext.tsx@@ -332,10 +332,10 @@ export function ShellModeProvider({);useEffect(() => {- if (!settingsEnabled) {+ if (catalog == null || capabilities?.settings?.enabled === false) {setSettingsOpenState(false);}- }, [settingsEnabled]);+ }, [capabilities?.settings?.enabled, catalog]);useEffect(() => {if (!sessionsEnabled) {diff --git a/packages/trueforge-ui/src/server/serverChrome.ts b/packages/trueforge-ui/src/server/serverChrome.tsindex 86b91ce92..95934a6c7 100644--- a/packages/trueforge-ui/src/server/serverChrome.ts+++ b/packages/trueforge-ui/src/server/serverChrome.ts@@ -12,7 +12,7 @@ export function isSettingsChromeEnabled({catalog: CatalogServer | null | undefined;capabilities: { settings?: { enabled?: boolean } } | null | undefined;}): boolean {- return catalog != null && capabilities?.settings?.enabled !== false;+ return catalog != null && capabilities?.settings?.enabled === true;}/** Sessions browser + agent-detail surfaces (Overview / sessions / code). */diff --git a/packages/trueforge-ui/test/containers/SettingsBuilder/index.test.tsx b/packages/trueforge-ui/test/containers/SettingsBuilder/index.test.tsxindex 9b913d33b..572721636 100644--- a/packages/trueforge-ui/test/containers/SettingsBuilder/index.test.tsx+++ b/packages/trueforge-ui/test/containers/SettingsBuilder/index.test.tsx@@ -83,8 +83,8 @@ function TestShell({ server, children }: { server?: AgentUIServer; children?: Re}async function openSettings() {- fireEvent.click(screen.getByRole('button', { name: 'Open settings' }));await waitFor(() => {+ fireEvent.click(screen.getByRole('button', { name: 'Open settings' }));expect(screen.getByRole('heading', { name: 'Settings' })).toBeInTheDocument();});}@@ -119,7 +119,7 @@ describe('TruefoundrySettingsBuilder', () => {rerender(<TestShell server={createServer({ skills: true, sandbox: true })} />);- fireEvent.click(screen.getByRole('button', { name: 'Skills' }));+ fireEvent.click(await screen.findByRole('button', { name: 'Skills' }));await waitFor(() => {expect(screen.getByText('Skill settings content')).toBeInTheDocument();});@@ -184,7 +184,7 @@ describe('TruefoundrySettingsBuilder', () => {const getSkills = vi.fn(async () => []);const getMcp = vi.fn(async () => []);const getCapabilities = vi.fn(async () => ({- data: { sandbox: { enabled: true }, skill: { enabled: true } },+ data: { sandbox: { enabled: true }, skill: { enabled: true }, settings: { enabled: true } },}));const server = createMockAgentUIServer({catalog: createMockCatalog(),diff --git a/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsx b/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsxindex 6ef256057..4b3757c64 100644--- a/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsx+++ b/packages/trueforge-ui/test/containers/TrueForgeUI.test.tsx@@ -585,7 +585,7 @@ describe('SidebarLayout', () => {expect(chatColumn?.querySelector('header')).toHaveClass('min-h-14');expect(screen.queryByRole('button', { name: 'Agent config' })).not.toBeInTheDocument();- const [settingsButton] = screen.getAllByRole('button', { name: 'Settings' });+ const [settingsButton] = await screen.findAllByRole('button', { name: 'Settings' });if (settingsButton === undefined) {throw new Error('Expected settings button');}@@ -612,7 +612,7 @@ describe('SidebarLayout', () => {</SlotsProvider>,);- expect(screen.getAllByRole('button', { name: 'Settings' })).toHaveLength(1);+ 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) {@@ -635,7 +635,7 @@ describe('SidebarLayout', () => {</ServerProvider></SlotsProvider>,);- expect(screen.getAllByRole('button', { name: 'Settings' })).toHaveLength(1);+ 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');@@ -822,7 +822,7 @@ describe('layout slot overrides', () => {expect(before.length).toBeGreaterThan(0);const beforeNode = before[0];- fireEvent.click(screen.getAllByRole('button', { name: 'Settings' })[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();diff --git a/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx b/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsxindex ab2786b3f..f4b7fff58 100644--- a/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx+++ b/packages/trueforge-ui/test/routing/ShellRouteSync.test.tsx@@ -43,12 +43,14 @@ function CaptureLocation() {function SettingsCatalogProvider({children,settingsEnabled = true,+ capabilitiesFail = false,includeCatalog = true,includeSessions = true,includeSchedules = false,}: {children: ReactNode;settingsEnabled?: boolean;+ capabilitiesFail?: boolean;includeCatalog?: boolean;includeSessions?: boolean;includeSchedules?: boolean;@@ -57,13 +59,16 @@ function SettingsCatalogProvider({...(includeCatalog ? { catalog: createMockCatalog() } : {}),...(includeSessions ? { sessions: createMockAgentSessionsServer() } : {}),...(includeSchedules ? { schedules: createMockScheduleServer() } : {}),- getCapabilities: async () => ({- data: {- sandbox: { enabled: true },- skill: { enabled: true },- settings: { enabled: settingsEnabled },- },- }),+ getCapabilities: async () => {+ if (capabilitiesFail) throw new Error('Unavailable');+ return {+ data: {+ sandbox: { enabled: true },+ skill: { enabled: true },+ settings: { enabled: settingsEnabled },+ },+ };+ },getSession: async ({ sessionId }) => ({id: sessionId,title: 'Session',@@ -80,6 +85,7 @@ function Harness({initialRemoteId,initialSettingsOpen = false,settingsEnabled = true,+ capabilitiesFail = false,includeCatalog = true,includeSessions = true,includeSchedules = false,@@ -88,6 +94,7 @@ function Harness({initialRemoteId?: string;initialSettingsOpen?: boolean;settingsEnabled?: boolean;+ capabilitiesFail?: boolean;includeCatalog?: boolean;includeSessions?: boolean;includeSchedules?: boolean;@@ -97,6 +104,7 @@ function Harness({return (<SettingsCatalogProvidersettingsEnabled={settingsEnabled}+ capabilitiesFail={capabilitiesFail}includeCatalog={includeCatalog}includeSessions={includeSessions}includeSchedules={includeSchedules}@@ -115,6 +123,7 @@ function renderSync(opts: {agentConfig?: AgentConfig;initialSettingsOpen?: boolean;settingsEnabled?: boolean;+ capabilitiesFail?: boolean;includeCatalog?: boolean;includeSessions?: boolean;includeSchedules?: boolean;@@ -125,6 +134,7 @@ function renderSync(opts: {agentConfig={opts.agentConfig}initialSettingsOpen={opts.initialSettingsOpen}settingsEnabled={opts.settingsEnabled}+ capabilitiesFail={opts.capabilitiesFail}includeCatalog={opts.includeCatalog}includeSessions={opts.includeSessions}includeSchedules={opts.includeSchedules}@@ -233,6 +243,14 @@ describe('ShellRouteSync', () => {expect(pathname).toBe('/');});+ it('unregisters /settings when capabilities fail to load', async () => {+ renderSync({ initialEntries: ['/settings'], capabilitiesFail: true });+ await waitFor(() => {+ expect(shell.settingsOpen).toBe(false);+ expect(pathname).toBe('/');+ });+ });+it('ignores initialSettingsOpen when Settings chrome has no catalog', async () => {renderSync({ initialEntries: ['/'], initialSettingsOpen: true, includeCatalog: false });await waitFor(() => {diff --git a/packages/trueforge-ui/test/server/ServerContext.test.tsx b/packages/trueforge-ui/test/server/ServerContext.test.tsxindex a01253c9a..2ad52193d 100644--- a/packages/trueforge-ui/test/server/ServerContext.test.tsx+++ b/packages/trueforge-ui/test/server/ServerContext.test.tsx@@ -13,6 +13,7 @@ import {useOptionalServer,useServer,useServerCapabilities,+ useServerCapabilitiesSettled,} from '@/server/ServerContext.js';import type { AgentUIServer, CatalogServer } from '@/server/types.js';import { createMockAgentUIServer } from './mockServer.js';@@ -141,6 +142,25 @@ describe('ServerProvider', () => {expect(result.current.capabilities).toEqual(initialCapabilities);});++ it('settles when the initial capabilities request fails', async () => {+ const server = createMockAgentUIServer({+ getCapabilities: async () => {+ throw new Error('Unavailable');+ },+ });+ const { result } = renderHook(+ () => ({+ capabilities: useServerCapabilities(),+ settled: useServerCapabilitiesSettled(),+ }),+ { wrapper: wrap(server) },+ );++ expect(result.current.settled).toBe(false);+ await waitFor(() => expect(result.current.settled).toBe(true));+ expect(result.current.capabilities).toBeNull();+ });});describe('useCatalogServer', () => {diff --git a/packages/trueforge-ui/test/server/ShellModeContext.test.tsx b/packages/trueforge-ui/test/server/ShellModeContext.test.tsxindex 2c3909020..5a9ffbbe3 100644--- a/packages/trueforge-ui/test/server/ShellModeContext.test.tsx+++ b/packages/trueforge-ui/test/server/ShellModeContext.test.tsx@@ -81,9 +81,10 @@ describe('ShellModeProvider', () => {expect(result.current).toBeNull();});- it('opens settings on first paint when initialSettingsOpen is true', () => {+ it('waits for explicit capability before honoring initialSettingsOpen', async () => {const { result } = renderHook(() => useShellMode(), { wrapper: wrap(undefined, true) });- expect(result.current.settingsOpen).toBe(true);+ expect(result.current.settingsOpen).toBe(false);+ await waitFor(() => expect(result.current.settingsOpen).toBe(true));expect(result.current.settingsSection).toBe('models');act(() => result.current.setSettingsOpen(false));@@ -99,24 +100,60 @@ describe('ShellModeProvider', () => {expect(result.current.settingsOpen).toBe(false);});- it('opens settings to a requested section', () => {- const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });+ it('ignores initialSettingsOpen when Settings capability is disabled', async () => {+ const server = createMockAgentUIServer({+ catalog: createMockCatalog(),+ getCapabilities: async () => ({+ data: {+ sandbox: { enabled: true },+ skill: { enabled: true },+ settings: { enabled: false },+ },+ }),+ });+ const { result } = renderHook(+ () => ({+ shell: useShellMode(),+ capabilities: useServerCapabilities(),+ }),+ {+ wrapper: function Wrapper({ children }: { children: ReactNode }) {+ return (+ <ServerProvider server={server}>+ <ShellModeProvider initialSettingsOpen>{children}</ShellModeProvider>+ </ServerProvider>+ );+ },+ },+ );- act(() => result.current.setSettingsOpen(true, 'connectors'));+ expect(result.current.shell.settingsOpen).toBe(false);+ await waitFor(() => expect(result.current.capabilities?.settings?.enabled).toBe(false));+ act(() => result.current.shell.setSettingsOpen(true));+ expect(result.current.shell.settingsOpen).toBe(false);+ });++ it('opens settings to a requested section', async () => {+ const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });- expect(result.current.settingsOpen).toBe(true);+ await waitFor(() => {+ act(() => result.current.setSettingsOpen(true, 'connectors'));+ expect(result.current.settingsOpen).toBe(true);+ });expect(result.current.settingsSection).toBe('connectors');});- it('closes the library when settings opens and vice versa', () => {+ it('closes the library when settings opens and vice versa', async () => {const { result } = renderHook(() => useShellMode(), { wrapper: wrap() });act(() => result.current.setLibraryOpen(true));expect(result.current.libraryOpen).toBe(true);expect(result.current.settingsOpen).toBe(false);- act(() => result.current.setSettingsOpen(true));- expect(result.current.settingsOpen).toBe(true);+ await waitFor(() => {+ act(() => result.current.setSettingsOpen(true));+ expect(result.current.settingsOpen).toBe(true);+ });expect(result.current.libraryOpen).toBe(false);act(() => result.current.setLibraryOpen(true));@@ -309,13 +346,15 @@ describe('ShellModeProvider', () => {expect(result.current.mode.status).toBe('idle');});- it('openDraft and selectAgent close Settings', () => {+ it('openDraft and selectAgent close Settings', async () => {const { result } = renderHook(() => useShellMode(), {wrapper: wrap({ mode: 'AgentLibraryWithComposer' }),});- act(() => result.current.setSettingsOpen(true));- expect(result.current.settingsOpen).toBe(true);+ await waitFor(() => {+ act(() => result.current.setSettingsOpen(true));+ expect(result.current.settingsOpen).toBe(true);+ });act(() => result.current.openDraft());expect(result.current.settingsOpen).toBe(false);diff --git a/packages/trueforge-ui/test/server/mockServer.ts b/packages/trueforge-ui/test/server/mockServer.tsindex 2f5f444ce..1b23bc057 100644--- a/packages/trueforge-ui/test/server/mockServer.ts+++ b/packages/trueforge-ui/test/server/mockServer.ts@@ -78,7 +78,7 @@ export function createMockAgentUIServer(overrides: Partial<AgentUIServer> = {}):getTurn: unavailable,listEvents: unavailable,getCapabilities: async () => ({- data: { sandbox: { enabled: true }, skill: { enabled: true } },+ data: { sandbox: { enabled: true }, skill: { enabled: true }, settings: { enabled: true } },}),getModels: async () => [],getSkills: async () => [],diff --git a/packages/trueforge-ui/test/server/serverChrome.test.ts b/packages/trueforge-ui/test/server/serverChrome.test.tsindex 76a684473..428cc1714 100644--- a/packages/trueforge-ui/test/server/serverChrome.test.ts+++ b/packages/trueforge-ui/test/server/serverChrome.test.ts@@ -22,9 +22,16 @@ describe('serverChrome', () => {const metrics = createMockAgentMetricsServer();const routes = resolveRoutesConfig();- it('isSettingsChromeEnabled requires catalog; missing settings capability counts as on', () => {+ it('isSettingsChromeEnabled requires a catalog and explicit capability', () => {expect(isSettingsChromeEnabled({ catalog: null, capabilities: null })).toBe(false);- expect(isSettingsChromeEnabled({ catalog, capabilities: null })).toBe(true);+ expect(isSettingsChromeEnabled({ catalog, capabilities: null })).toBe(false);+ expect(isSettingsChromeEnabled({ catalog, capabilities: {} })).toBe(false);+ expect(+ isSettingsChromeEnabled({+ catalog,+ capabilities: { settings: { enabled: true } },+ }),+ ).toBe(true);expect(isSettingsChromeEnabled({catalog,diff --git a/packages/trueforge-ui/test/server/settingsChrome.test.ts b/packages/trueforge-ui/test/server/settingsChrome.test.tsindex 82858f327..f465d0bef 100644--- a/packages/trueforge-ui/test/server/settingsChrome.test.ts+++ b/packages/trueforge-ui/test/server/settingsChrome.test.ts@@ -7,9 +7,10 @@ import { createMockCatalog } from './mockServer.js';describe('isSettingsChromeEnabled', () => {const catalog = createMockCatalog();- it('requires a catalog and treats missing settings capability as enabled', () => {+ it('requires a catalog and explicit settings capability', () => {expect(isSettingsChromeEnabled({ catalog: null, capabilities: null })).toBe(false);- expect(isSettingsChromeEnabled({ catalog, capabilities: null })).toBe(true);+ expect(isSettingsChromeEnabled({ catalog, capabilities: null })).toBe(false);+ expect(isSettingsChromeEnabled({ catalog, capabilities: {} })).toBe(false);expect(isSettingsChromeEnabled({catalog,