Skip to content

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.md
new file mode 100644
index 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.tsx
index 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.tsx
index 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.tsx
index 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.tsx
index 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.ts
index 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.tsx
index 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.tsx
index 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.tsx
index 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 (
<SettingsCatalogProvider
settingsEnabled={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.tsx
index 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.tsx
index 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.ts
index 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.ts
index 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.ts
index 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,