Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

Add logout functionality and session management (#90)

Sujai Kumar Guptaa2039d1748de
diff --git a/fern/openapi/openapi.json b/fern/openapi/openapi.json
index 4ad9b6ebd..0545640cc 100644
--- a/fern/openapi/openapi.json
+++ b/fern/openapi/openapi.json
@@ -4149,7 +4149,7 @@
],
"responses": {
"302": {
- "description": "Redirect back into the app on success, or to /?error=login_failed on failure."
+ "description": "Redirect back into the app on success, or to /?error=<reason> on failure."
}
},
"summary": "Login callback",
diff --git a/packages/frontend/src/App.tsx b/packages/frontend/src/App.tsx
index 394579627..4f1428ffd 100644
--- a/packages/frontend/src/App.tsx
+++ b/packages/frontend/src/App.tsx
@@ -7,10 +7,14 @@ import {
type WelcomeScreenProps,
} from '@truefoundry/trueforge-ui';
import { useEffect, useMemo, useRef, useState } from 'react';
+import { AuthErrorScreen } from './AuthErrorScreen';
+import { isLoggedOutSearch, parseAuthErrorReason } from './authStatusSearch';
import { getCapabilities, listModels } from './composerLists';
import { createConnectorCatalog } from './connectorCatalog';
import { createHarnessBuilderServer } from './harnessBuilderServer';
import { createHarnessChatServer, type HarnessAgentSpec } from './harnessServer';
+import { LoggedOutScreen } from './LoggedOutScreen';
+import { LogoutButton } from './LogoutButton';
import { createModelProviderCatalog } from './modelProviderCatalog';
import { createSandboxProviderCatalog } from './sandboxProviderCatalog';
import { createSkillCatalog } from './skillCatalog';
@@ -48,9 +52,16 @@ type BootState =
| { status: 'ready'; defaultAgentSpec: HarnessAgentSpec; openSettings: boolean };
export function App() {
+ const search = window.location.search;
+ const loggedOut = isLoggedOutSearch(search);
+ const authError = parseAuthErrorReason(search);
+ const skipBoot = loggedOut || authError != null;
const [boot, setBoot] = useState<BootState>({ status: 'loading' });
useEffect(() => {
+ if (skipBoot) {
+ return;
+ }
const state = { cancelled: false };
void (async () => {
try {
@@ -95,15 +106,24 @@ export function App() {
return () => {
state.cancelled = true;
};
- }, []);
+ }, [skipBoot]);
const overrides: SlotOverrides = useMemo(
() => ({
+ ShellActionsActionSlot: LogoutButton,
...(boot.status === 'ready' && boot.openSettings ? { WelcomeScreen: OpenSettingsWelcomeScreen } : {}),
}),
[boot],
);
+ if (loggedOut) {
+ return <LoggedOutScreen />;
+ }
+
+ if (authError != null) {
+ return <AuthErrorScreen reason={authError} />;
+ }
+
if (boot.status === 'error') {
return (
<div className="boot-screen" data-error="true">
diff --git a/packages/frontend/src/AuthErrorScreen.tsx b/packages/frontend/src/AuthErrorScreen.tsx
new file mode 100644
index 000000000..494d0fefe
--- /dev/null
+++ b/packages/frontend/src/AuthErrorScreen.tsx
@@ -0,0 +1,12 @@
+import { AuthStatusCard } from './AuthStatusCard';
+
+/** OIDC / login failure status. */
+export function AuthErrorScreen({ reason }: { reason: string }) {
+ return (
+ <AuthStatusCard
+ kind="error"
+ title="Sign-in failed"
+ description={reason === 'login_failed' ? 'We could not complete sign-in. Return home to try again.' : reason}
+ />
+ );
+}
diff --git a/packages/frontend/src/AuthStatusCard.css b/packages/frontend/src/AuthStatusCard.css
new file mode 100644
index 000000000..f68e12d30
--- /dev/null
+++ b/packages/frontend/src/AuthStatusCard.css
@@ -0,0 +1,74 @@
+/* Shared by AuthErrorScreen / LoggedOutScreen — mirrors PostMcpOauthScreen layout. */
+
+.auth-status {
+ min-height: 100dvh;
+ display: flex;
+ align-items: center;
+ justify-content: center;
+ padding: 1.5rem;
+ background: var(--background);
+ color: var(--foreground);
+}
+
+.auth-status-card {
+ display: flex;
+ width: 100%;
+ max-width: 28rem;
+ flex-direction: column;
+ align-items: center;
+ gap: 0.75rem;
+ border: 1px solid color-mix(in srgb, var(--foreground) 12%, transparent);
+ border-radius: 1rem;
+ background: color-mix(in srgb, var(--background) 88%, var(--foreground));
+ padding: 2rem;
+ text-align: center;
+ box-shadow: 0 1px 2px color-mix(in srgb, #000 20%, transparent);
+}
+
+.auth-status-icon {
+ width: 4rem;
+ height: 4rem;
+ flex-shrink: 0;
+}
+
+.auth-status-icon--success {
+ color: #4ade80;
+}
+
+.auth-status-icon--error {
+ color: var(--destructive);
+}
+
+.auth-status-title {
+ margin: 0;
+ font-size: 1.5rem;
+ font-weight: 600;
+ line-height: 1.25;
+ color: var(--foreground);
+}
+
+.auth-status-description {
+ margin: 0;
+ font-size: 0.875rem;
+ line-height: 1.5rem;
+ color: var(--muted-foreground);
+}
+
+.auth-status-home {
+ margin-top: 0.75rem;
+ display: inline-flex;
+ min-height: 2.25rem;
+ align-items: center;
+ justify-content: center;
+ border-radius: 0.5rem;
+ padding: 0 1rem;
+ background: var(--foreground);
+ color: var(--background);
+ font-size: 0.875rem;
+ font-weight: 600;
+ text-decoration: none;
+}
+
+.auth-status-home:hover {
+ filter: brightness(0.92);
+}
diff --git a/packages/frontend/src/AuthStatusCard.tsx b/packages/frontend/src/AuthStatusCard.tsx
new file mode 100644
index 000000000..53aa5a8f6
--- /dev/null
+++ b/packages/frontend/src/AuthStatusCard.tsx
@@ -0,0 +1,45 @@
+import type { ReactNode } from 'react';
+import './AuthStatusCard.css';
+
+export type AuthStatusKind = 'success' | 'error';
+
+function StatusIcon({ kind }: { kind: AuthStatusKind }): ReactNode {
+ if (kind === 'success') {
+ return (
+ <svg className="auth-status-icon auth-status-icon--success" viewBox="0 0 64 64" aria-hidden>
+ <circle cx="32" cy="32" r="30" fill="none" stroke="currentColor" strokeWidth="3" />
+ <path
+ d="M18 33.5 27.5 43 46 22"
+ fill="none"
+ stroke="currentColor"
+ strokeWidth="3.5"
+ strokeLinecap="round"
+ strokeLinejoin="round"
+ />
+ </svg>
+ );
+ }
+
+ return (
+ <svg className="auth-status-icon auth-status-icon--error" viewBox="0 0 64 64" aria-hidden>
+ <circle cx="32" cy="32" r="30" fill="none" stroke="currentColor" strokeWidth="3" />
+ <path d="M22 22 42 42M42 22 22 42" fill="none" stroke="currentColor" strokeWidth="3.5" strokeLinecap="round" />
+ </svg>
+ );
+}
+
+/** Centered card shell (same layout idea as {@link PostMcpOauthScreen}). */
+export function AuthStatusCard(params: { kind: AuthStatusKind; title: string; description: string }) {
+ return (
+ <main className="auth-status">
+ <div className="auth-status-card">
+ <StatusIcon kind={params.kind} />
+ <h1 className="auth-status-title">{params.title}</h1>
+ <p className="auth-status-description">{params.description}</p>
+ <a className="auth-status-home" href="/">
+ Go to home
+ </a>
+ </div>
+ </main>
+ );
+}
diff --git a/packages/frontend/src/LoggedOutScreen.tsx b/packages/frontend/src/LoggedOutScreen.tsx
new file mode 100644
index 000000000..bb6890e23
--- /dev/null
+++ b/packages/frontend/src/LoggedOutScreen.tsx
@@ -0,0 +1,12 @@
+import { AuthStatusCard } from './AuthStatusCard';
+
+/** Post-logout confirmation (not an error). */
+export function LoggedOutScreen() {
+ return (
+ <AuthStatusCard
+ kind="success"
+ title="Signed out"
+ description="Your session has ended. Return home to sign in again."
+ />
+ );
+}
diff --git a/packages/frontend/src/LogoutButton.tsx b/packages/frontend/src/LogoutButton.tsx
new file mode 100644
index 000000000..db636ae3e
--- /dev/null
+++ b/packages/frontend/src/LogoutButton.tsx
@@ -0,0 +1,58 @@
+import { Icon } from '@truefoundry/trueforge-ui';
+import { useEffect, useState } from 'react';
+import { AUTH_LOGGED_OUT_HREF } from './authFetch';
+import { getCachedIsOidcConnectedSession, isOidcConnectedSession, logout } from './authSession';
+
+/**
+ * Icon button next to Settings (via `ShellActionsActionSlot` override).
+ * Shown only when `auth.me()` returns `type: "oidc-connected"`.
+ * Uses a module cache so remounts of the action slot do not hide the control during refetches.
+ */
+export function LogoutButton() {
+ const [visible, setVisible] = useState(() => getCachedIsOidcConnectedSession() === true);
+ const [busy, setBusy] = useState(false);
+
+ useEffect(() => {
+ const state = { cancelled: false };
+ void isOidcConnectedSession()
+ .then(ok => {
+ if (!state.cancelled) setVisible(ok);
+ })
+ .catch(() => {
+ // Failed refetch must not clear a known-good session (e.g. transient network).
+ if (!state.cancelled && getCachedIsOidcConnectedSession() === undefined) {
+ setVisible(false);
+ }
+ });
+ return () => {
+ state.cancelled = true;
+ };
+ }, []);
+
+ if (!visible) {
+ return null;
+ }
+
+ return (
+ <button
+ type="button"
+ aria-label="Log out"
+ title="Log out"
+ disabled={busy}
+ className="harness-logout"
+ onClick={() => {
+ if (busy) return;
+ setBusy(true);
+ void logout()
+ .then(() => {
+ window.location.assign(AUTH_LOGGED_OUT_HREF);
+ })
+ .catch(() => {
+ setBusy(false);
+ });
+ }}
+ >
+ <Icon name="log-out" />
+ </button>
+ );
+}
diff --git a/packages/frontend/src/authFetch.ts b/packages/frontend/src/authFetch.ts
new file mode 100644
index 000000000..f43703000
--- /dev/null
+++ b/packages/frontend/src/authFetch.ts
@@ -0,0 +1,32 @@
+/**
+ * Browser auth entry points. Login is not an SDK method (302 browser flow).
+ * On any HTTP 401, redirect to OIDC login (session required).
+ */
+
+/** Browser entry for OIDC login (not available as an SDK method). */
+export const AUTH_LOGIN_HREF = '/api/v1/auth/login';
+
+/** Post-logout landing (separate from login failure `?error=`). */
+export const AUTH_LOGGED_OUT_HREF = '/?logged_out';
+
+export function createAuthAwareFetch(baseFetch: typeof fetch = globalThis.fetch.bind(globalThis)): typeof fetch {
+ let redirecting = false;
+
+ return async (input, init) => {
+ const response = await baseFetch(input, init);
+
+ if (response.status !== 401 || typeof window === 'undefined') {
+ return response;
+ }
+
+ if (!redirecting) {
+ redirecting = true;
+ window.location.assign(AUTH_LOGIN_HREF);
+ }
+
+ // Do not surface 401 to callers — boot would flash a config error before navigation.
+ return new Promise<Response>(resolve => {
+ void resolve;
+ });
+ };
+}
diff --git a/packages/frontend/src/authSession.ts b/packages/frontend/src/authSession.ts
new file mode 100644
index 000000000..383257fea
--- /dev/null
+++ b/packages/frontend/src/authSession.ts
@@ -0,0 +1,35 @@
+/**
+ * Session helpers: SDK `auth.me()` / `auth.logout()` only.
+ * Login is not on the SDK (browser redirect to `/api/v1/auth/login`).
+ */
+import type { TrueForgeApi as Harness, TrueForge } from 'trueforge';
+import { harnessClient } from './harnessClient';
+
+export type MeResponse = Harness.MeResponse;
+
+/** Last successful me() OIDC check — survives remounts of host chrome. */
+let cachedIsOidcConnected: boolean | undefined;
+
+export function getCachedIsOidcConnectedSession(): boolean | undefined {
+ return cachedIsOidcConnected;
+}
+
+/** Test-only: clear the module cache between cases. */
+export function resetOidcSessionCacheForTests(): void {
+ cachedIsOidcConnected = undefined;
+}
+
+/**
+ * True when the current session is a browser OIDC login (`type: "oidc-connected"`).
+ * When OIDC is configured, unauthenticated callers get HTTP 401 from `/me`.
+ */
+export async function isOidcConnectedSession(client: TrueForge = harnessClient): Promise<boolean> {
+ const session = await client.auth.me();
+ const isConnected = session.type === 'oidc-connected';
+ cachedIsOidcConnected = isConnected;
+ return isConnected;
+}
+
+export async function logout(client: TrueForge = harnessClient): Promise<void> {
+ await client.auth.logout();
+}
diff --git a/packages/frontend/src/authStatusSearch.ts b/packages/frontend/src/authStatusSearch.ts
new file mode 100644
index 000000000..f8a4fefac
--- /dev/null
+++ b/packages/frontend/src/authStatusSearch.ts
@@ -0,0 +1,13 @@
+/** True when the URL is a logout landing (`/?logged_out`). */
+export function isLoggedOutSearch(search: string): boolean {
+ return new URLSearchParams(search).has('logged_out');
+}
+
+/** Reads `/?error=<reason>` from OIDC login failures. Returns null when not an error landing. */
+export function parseAuthErrorReason(search: string): string | null {
+ const reason = new URLSearchParams(search).get('error')?.trim();
+ if (!reason) {
+ return null;
+ }
+ return reason;
+}
diff --git a/packages/frontend/src/harnessClient.ts b/packages/frontend/src/harnessClient.ts
index 85b4392f2..aaac5182f 100644
--- a/packages/frontend/src/harnessClient.ts
+++ b/packages/frontend/src/harnessClient.ts
@@ -2,8 +2,11 @@
* Shared TrueForge HTTP client for the Harness host app.
* One place for baseUrl / future auth (headers, API key) so catalog adapters
* and the chat server do not each construct their own client.
+ *
+ * Default `fetch` intercepts 401 and sends the browser through OIDC login.
*/
import { TrueForge } from 'trueforge';
+import { createAuthAwareFetch } from './authFetch';
export interface CreateHarnessClientOptions {
baseUrl?: string;
@@ -15,7 +18,7 @@ const DEFAULT_BASE_URL = '/';
export function createHarnessClient(options: CreateHarnessClientOptions = {}): TrueForge {
return new TrueForge({
baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
- ...(options.fetch ? { fetch: options.fetch } : {}),
+ fetch: createAuthAwareFetch(options.fetch ?? globalThis.fetch.bind(globalThis)),
});
}
diff --git a/packages/frontend/src/index.css b/packages/frontend/src/index.css
index e67dcf62d..87b0dc5a1 100644
--- a/packages/frontend/src/index.css
+++ b/packages/frontend/src/index.css
@@ -45,3 +45,27 @@ body {
.boot-screen[data-error='true'] {
color: var(--destructive);
}
+
+.harness-logout {
+ display: inline-flex;
+ height: 2rem;
+ width: 2rem;
+ flex-shrink: 0;
+ align-items: center;
+ justify-content: center;
+ border: 0;
+ border-radius: 0.375rem;
+ background: transparent;
+ color: inherit;
+ cursor: pointer;
+}
+
+.harness-logout:hover:not(:disabled) {
+ background: color-mix(in srgb, currentColor 10%, transparent);
+}
+
+.harness-logout:disabled {
+ opacity: 0.5;
+ cursor: default;
+ pointer-events: none;
+}
diff --git a/packages/frontend/tests/authFetch.test.ts b/packages/frontend/tests/authFetch.test.ts
new file mode 100644
index 000000000..76aaa5f40
--- /dev/null
+++ b/packages/frontend/tests/authFetch.test.ts
@@ -0,0 +1,71 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import { AUTH_LOGGED_OUT_HREF, AUTH_LOGIN_HREF, createAuthAwareFetch } from '../src/authFetch';
+import { isLoggedOutSearch, parseAuthErrorReason } from '../src/authStatusSearch';
+
+describe('createAuthAwareFetch', () => {
+ it('passes through non-401 responses', async () => {
+ const wrapped = createAuthAwareFetch(async () => new Response('ok', { status: 200 }));
+ const response = await wrapped('/api/v1/models');
+ assert.equal(response.status, 200);
+ });
+
+ it('does not redirect on 401 when window is undefined', async () => {
+ const wrapped = createAuthAwareFetch(async () => new Response('nope', { status: 401 }));
+ const response = await wrapped('/api/v1/models');
+ assert.equal(response.status, 401);
+ });
+
+ it('redirects once on 401 and does not return the failing response', async () => {
+ const originalWindow = globalThis.window;
+ const assigns: string[] = [];
+ // Minimal browser stub for the redirect path.
+ (globalThis as { window: Window }).window = {
+ location: {
+ assign: (href: string) => {
+ assigns.push(href);
+ },
+ },
+ } as Window;
+
+ try {
+ const wrapped = createAuthAwareFetch(async () => new Response('nope', { status: 401 }));
+ let settled = false;
+ void wrapped('/api/v1/models').then(() => {
+ settled = true;
+ });
+ await new Promise(resolve => setTimeout(resolve, 20));
+ assert.deepEqual(assigns, [AUTH_LOGIN_HREF]);
+ assert.equal(settled, false);
+ // Second 401 must not double-redirect.
+ void wrapped('/api/v1/models');
+ await new Promise(resolve => setTimeout(resolve, 20));
+ assert.deepEqual(assigns, [AUTH_LOGIN_HREF]);
+ } finally {
+ if (originalWindow === undefined) {
+ // node --test has no window by default
+ Reflect.deleteProperty(globalThis, 'window');
+ } else {
+ (globalThis as { window: Window }).window = originalWindow;
+ }
+ }
+ });
+
+ it('exports browser auth entry paths', () => {
+ assert.equal(AUTH_LOGIN_HREF, '/api/v1/auth/login');
+ assert.equal(AUTH_LOGGED_OUT_HREF, '/?logged_out');
+ });
+});
+
+describe('auth status landings', () => {
+ it('detects logout landing separately from errors', () => {
+ assert.equal(isLoggedOutSearch('?logged_out'), true);
+ assert.equal(isLoggedOutSearch('?logged_out='), true);
+ assert.equal(isLoggedOutSearch('?error=login_failed'), false);
+ });
+
+ it('reads error reason for sign-in failures', () => {
+ assert.equal(parseAuthErrorReason('?error=access_denied'), 'access_denied');
+ assert.equal(parseAuthErrorReason('?logged_out'), null);
+ });
+});
diff --git a/packages/frontend/tests/authSession.test.ts b/packages/frontend/tests/authSession.test.ts
new file mode 100644
index 000000000..ec9d05b89
--- /dev/null
+++ b/packages/frontend/tests/authSession.test.ts
@@ -0,0 +1,61 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import type { TrueForge } from 'trueforge';
+import {
+ getCachedIsOidcConnectedSession,
+ isOidcConnectedSession,
+ logout,
+ resetOidcSessionCacheForTests,
+} from '../src/authSession';
+
+function createClient(params: {
+ type?: 'default' | 'oidc-connected';
+ onLogout?: () => void;
+ meError?: Error;
+}): TrueForge {
+ return {
+ auth: {
+ me: async () => {
+ if (params.meError != null) throw params.meError;
+ return {
+ type: params.type ?? 'default',
+ email: '[email protected]',
+ role: 'user',
+ };
+ },
+ logout: async () => {
+ params.onLogout?.();
+ },
+ },
+ } as unknown as TrueForge;
+}
+
+describe('authSession', () => {
+ it('detects oidc-connected sessions via auth.me and caches the result', async () => {
+ resetOidcSessionCacheForTests();
+ assert.equal(getCachedIsOidcConnectedSession(), undefined);
+ assert.equal(await isOidcConnectedSession(createClient({ type: 'oidc-connected' })), true);
+ assert.equal(getCachedIsOidcConnectedSession(), true);
+ assert.equal(await isOidcConnectedSession(createClient({ type: 'default' })), false);
+ assert.equal(getCachedIsOidcConnectedSession(), false);
+ });
+
+ it('does not clear the cache when auth.me fails', async () => {
+ resetOidcSessionCacheForTests();
+ assert.equal(await isOidcConnectedSession(createClient({ type: 'oidc-connected' })), true);
+ await assert.rejects(() => isOidcConnectedSession(createClient({ meError: new Error('network') })), /network/);
+ assert.equal(getCachedIsOidcConnectedSession(), true);
+ });
+
+ it('delegates logout to auth.logout', async () => {
+ let called = false;
+ await logout(
+ createClient({
+ onLogout: () => {
+ called = true;
+ },
+ }),
+ );
+ assert.equal(called, true);
+ });
+});
diff --git a/packages/server/src/apis/auth.ts b/packages/server/src/apis/auth.ts
index 4e3dbb3b3..f534cd2a7 100644
--- a/packages/server/src/apis/auth.ts
+++ b/packages/server/src/apis/auth.ts
@@ -8,7 +8,10 @@ import { buildLoginAuthorization, exchangeAuthorizationCode, getOidcVerify, safe
import { authLoginRoute, authLogoutRoute, meRoute, oAuthCallbackRoute } from '../routes/authRoutes';
import type { MeResponse } from '../schemas/auth';
-const LOGIN_ERROR_PATH = '/?error=login_failed';
+/** Login / OIDC failures land on `/?error=<reason>`. */
+function oauthErrorRedirect(reason: string): string {
+ return `/?error=${encodeURIComponent(reason)}`;
+}
/**
* Auth surfaces mounted at /api/v1/auth: login, callback, logout, me.
@@ -34,7 +37,7 @@ export function createAuthRouter(params: { oidcClient: Configuration | undefined
params.logger.error('Failed to build login authorization', {
error: error instanceof Error ? error.message : error,
});
- return c.redirect(LOGIN_ERROR_PATH, 302);
+ return c.redirect(oauthErrorRedirect('login_failed'), 302);
}
});
@@ -48,8 +51,15 @@ export function createAuthRouter(params: { oidcClient: Configuration | undefined
clearAuthCookie({ context: c, name: OAUTH_STATE_COOKIE });
if (pending?.state !== query.state || query.error || !query.code) {
- // TODO: handle the error here once frontend error page is implemented
- return c.redirect(LOGIN_ERROR_PATH, 302);
+ const description = query.error_description?.trim();
+ const errorCode = query.error?.trim();
+ let reason = 'login_failed';
+ if (description) {
+ reason = description;
+ } else if (errorCode) {
+ reason = errorCode;
+ }
+ return c.redirect(oauthErrorRedirect(reason), 302);
}
try {
@@ -65,8 +75,8 @@ export function createAuthRouter(params: { oidcClient: Configuration | undefined
params.logger.error('Failed to exchange authorization code', {
error: error instanceof Error ? error.message : error,
});
- // TODO: handle the error here once frontend error page is implemented
- return c.redirect(LOGIN_ERROR_PATH, 302);
+ const reason = error instanceof Error ? error.message : 'login_failed';
+ return c.redirect(oauthErrorRedirect(reason), 302);
}
});
diff --git a/packages/server/src/routes/authRoutes.ts b/packages/server/src/routes/authRoutes.ts
index b53523360..85813a654 100644
--- a/packages/server/src/routes/authRoutes.ts
+++ b/packages/server/src/routes/authRoutes.ts
@@ -36,7 +36,7 @@ export const oAuthCallbackRoute = createRoute({
'x-fern-ignore': true,
request: { query: OAuthCallbackQuerySchema },
responses: {
- 302: { description: 'Redirect back into the app on success, or to /?error=login_failed on failure.' },
+ 302: { description: 'Redirect back into the app on success, or to /?error=<reason> on failure.' },
},
});
diff --git a/packages/server/tests/unit/apis/auth.test.ts b/packages/server/tests/unit/apis/auth.test.ts
index babc71148..26f35349b 100644
--- a/packages/server/tests/unit/apis/auth.test.ts
+++ b/packages/server/tests/unit/apis/auth.test.ts
@@ -222,6 +222,23 @@ describe('auth router (OIDC configured)', () => {
expect(idTokenCookie).toContain('Max-Age=86400');
});
+ it('GET /callback redirects home with error when the IdP returns an error', async () => {
+ const res = await createAuthRouter({ oidcClient, logger }).request(
+ '/callback?state=any&error=access_denied&error_description=user%20cancelled',
+ { redirect: 'manual' },
+ );
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe('/?error=user%20cancelled');
+ });
+
+ it('GET /callback redirects home with error when state mismatches', async () => {
+ const res = await createAuthRouter({ oidcClient, logger }).request('/callback?code=abc&state=wrong', {
+ redirect: 'manual',
+ });
+ expect(res.status).toBe(302);
+ expect(res.headers.get('location')).toBe('/?error=login_failed');
+ });
+
it('POST /logout clears id_token even when no cookie is present', async () => {
const res = await createAuthRouter({ oidcClient, logger }).request('/logout', {
method: 'POST',
diff --git a/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx b/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx
index be62df9a0..a8327e455 100644
--- a/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx
+++ b/packages/trueforge-ui-sdk/src/atoms/ShellActions.tsx
@@ -3,6 +3,7 @@
import { Icon } from '../icons/Icon.js';
import { useOptionalCatalogServer, useServerCapabilities } from '../server/ServerContext.js';
import { useOptionalShellMode } from '../server/ShellModeContext.js';
+import { useSlot } from '../theme/SlotsProvider.js';
import { useTheme } from '../theme/ThemeProvider.js';
import { auiButtonClass } from './lib/buttonClasses.js';
import { cn } from './lib/cn.js';
@@ -12,6 +13,7 @@ export function ShellActions({ className }: { className?: string }) {
const catalog = useOptionalCatalogServer();
const capabilities = useServerCapabilities();
const { mode, setTheme } = useTheme();
+ const ActionSlot = useSlot('ShellActionsActionSlot');
return (
<div className={cn('flex shrink-0 items-center gap-1 text-foreground', className)}>
@@ -36,6 +38,7 @@ export function ShellActions({ className }: { className?: string }) {
<Icon name="settings" />
</button>
) : null}
+ <ActionSlot />
</div>
);
}
diff --git a/packages/trueforge-ui-sdk/src/atoms/ShellActionsActionSlot.tsx b/packages/trueforge-ui-sdk/src/atoms/ShellActionsActionSlot.tsx
new file mode 100644
index 000000000..53d49a4a6
--- /dev/null
+++ b/packages/trueforge-ui-sdk/src/atoms/ShellActionsActionSlot.tsx
@@ -0,0 +1,18 @@
+'use client';
+
+import type { ReactNode } from 'react';
+
+/**
+ * Optional host chrome (e.g. logout) to the right of theme + settings in {@link ShellActions}.
+ * Default is empty; override via `overrides.ShellActionsActionSlot`.
+ * Layouts keep {@link ShellActions} mounted while Settings is open so host state is not remounted.
+ */
+export function ShellActionsActionSlot(): ReactNode {
+ return null;
+}
+
+declare module '../theme/SlotsProvider.js' {
+ interface AtomSlots {
+ ShellActionsActionSlot: typeof ShellActionsActionSlot;
+ }
+}
diff --git a/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx b/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx
index d532f7216..0b00ebc8f 100644
--- a/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx
+++ b/packages/trueforge-ui-sdk/src/icons/IconRegistry.tsx
@@ -31,6 +31,7 @@ import {
ListOrdered,
Loader2,
Lock,
+ LogOut,
Maximize2,
Menu,
Minimize2,
@@ -105,6 +106,7 @@ const defaults: Record<string, LucideIcon> = {
sun: Sun,
moon: Moon,
settings: Settings,
+ 'log-out': LogOut,
search: Search,
clock: Clock,
'circle-check': CircleCheck,
diff --git a/packages/trueforge-ui-sdk/src/index.ts b/packages/trueforge-ui-sdk/src/index.ts
index ae576d7f2..4367a4c87 100644
--- a/packages/trueforge-ui-sdk/src/index.ts
+++ b/packages/trueforge-ui-sdk/src/index.ts
@@ -218,6 +218,7 @@ export type {
// Server port types + factory
export { ClearChatButton } from './atoms/ClearChatButton.js';
export { SelectAgentEmptyState } from './atoms/SelectAgentEmptyState.js';
+export { ShellActionsActionSlot } from './atoms/ShellActionsActionSlot.js';
export { createTrueFoundryServer } from './server/createTrueFoundryServer.js';
export type { CreateTrueFoundryServerOptions, TrueFoundryServer } from './server/createTrueFoundryServer.js';
export {
diff --git a/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx
index 0683dcb64..d3066cf2a 100644
--- a/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx
+++ b/packages/trueforge-ui-sdk/src/layouts/DrawerLayout.tsx
@@ -64,36 +64,45 @@ export function DrawerLayout({ className }: { className?: string }) {
return (
<div className={cn('relative flex h-full min-h-0 w-full flex-col', className)}>
- {!settingsOpen ? (
- <header className="flex shrink-0 items-center gap-1 border-b border-border bg-background px-2 py-1.5">
- <NamedAgentHeaderLabel />
+ {/* Keep ShellActions mounted across Settings open/close so host action-slot state persists. */}
+ <header className="flex shrink-0 items-center gap-1 border-b border-border bg-background px-2 py-1.5">
+ {!settingsOpen ? (
+ <>
+ <NamedAgentHeaderLabel />
+ <span className="min-w-0 flex-1" />
+ <ClearChatButton />
+ <SaveAgentButton />
+ </>
+ ) : (
<span className="min-w-0 flex-1" />
- <ClearChatButton />
- <SaveAgentButton />
- <ShellActions />
- {shell?.isNewChatEnabled !== false ? (
+ )}
+ <ShellActions key="shell-actions" />
+ {!settingsOpen ? (
+ <>
+ {shell?.isNewChatEnabled !== false ? (
+ <button
+ type="button"
+ aria-label="New chat"
+ title="New chat"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={handleNewChat}
+ >
+ <Icon name="plus" />
+ </button>
+ ) : null}
<button
+ ref={threadsBtnRef}
type="button"
- aria-label="New chat"
- title="New chat"
- className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
- onClick={handleNewChat}
+ aria-label="Sessions"
+ aria-expanded={threadsOpen}
+ className="text-muted-foreground hover:text-foreground inline-flex size-8 cursor-pointer items-center justify-center rounded-md"
+ onClick={() => setThreadsOpen(v => !v)}
>
- <Icon name="plus" />
+ <Icon name="clock-rotate-left" />
</button>
- ) : null}
- <button
- ref={threadsBtnRef}
- type="button"
- aria-label="Sessions"
- aria-expanded={threadsOpen}
- className="text-muted-foreground hover:text-foreground inline-flex size-8 cursor-pointer items-center justify-center rounded-md"
- onClick={() => setThreadsOpen(v => !v)}
- >
- <Icon name="clock-rotate-left" />
- </button>
- </header>
- ) : null}
+ </>
+ ) : null}
+ </header>
<div ref={mainRef} className="min-h-0 min-w-0 flex-1">
{settingsOpen ? <TruefoundrySettingsBuilder /> : isIdle ? <SelectAgentEmptyState /> : <Thread />}
</div>
diff --git a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
index 8427a9a5f..c1e43848e 100644
--- a/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
+++ b/packages/trueforge-ui-sdk/src/layouts/SidebarLayout.tsx
@@ -138,33 +138,39 @@ export function SidebarLayout({ className }: { className?: string }) {
</aside>
<div className="flex min-h-0 min-w-0 flex-1 flex-col">
- {/* Thread header: always on mobile; on desktop when Clear Chat / Save are relevant. Hidden while Settings owns the pane. */}
- {!settingsOpen ? (
- <header
- className={cn(
- 'flex shrink-0 items-center gap-1 border-b border-border bg-background px-2 py-1.5',
- isIdle && 'md:hidden',
- )}
- >
- <button
- ref={menuBtnRef}
- type="button"
- aria-label="Sessions"
- aria-expanded={mobileNavOpen}
- className={cn(auiButtonClass({ variant: 'ghost', size: 'icon' }), 'md:hidden')}
- onClick={() => setMobileNavOpen(true)}
- >
- <Icon name="bars" />
- </button>
- <NamedAgentHeaderLabel />
+ {/* Mobile ShellActions stay mounted while Settings is open so host overrides (e.g. logout) do not remount.
+ Desktop keeps shell chrome in the aside footer (always mounted). */}
+ <header
+ className={cn(
+ 'flex shrink-0 items-center gap-1 border-b border-border bg-background px-2 py-1.5',
+ // Settings / idle: desktop uses aside chrome; mobile still needs ShellActions.
+ (settingsOpen || isIdle) && 'md:hidden',
+ )}
+ >
+ {!settingsOpen ? (
+ <>
+ <button
+ ref={menuBtnRef}
+ type="button"
+ aria-label="Sessions"
+ aria-expanded={mobileNavOpen}
+ className={cn(auiButtonClass({ variant: 'ghost', size: 'icon' }), 'md:hidden')}
+ onClick={() => setMobileNavOpen(true)}
+ >
+ <Icon name="bars" />
+ </button>
+ <NamedAgentHeaderLabel />
+ <span className="min-w-0 flex-1" />
+ <ClearChatButton />
+ <SaveAgentButton />
+ </>
+ ) : (
<span className="min-w-0 flex-1" />
- <ClearChatButton />
- <SaveAgentButton />
- <div className="md:hidden">
- <ShellActions />
- </div>
- </header>
- ) : null}
+ )}
+ <div key="mobile-shell-actions" className="md:hidden">
+ <ShellActions />
+ </div>
+ </header>
<div ref={mainRef} className="min-h-0 min-w-0 flex-1">
{settingsOpen ? <TruefoundrySettingsBuilder /> : isIdle ? <SelectAgentEmptyState /> : <Thread />}
diff --git a/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx b/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx
index bd9cb1b92..06579a4fa 100644
--- a/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx
+++ b/packages/trueforge-ui-sdk/src/layouts/StackChatPanel.tsx
@@ -39,45 +39,39 @@ export function StackChatPanel({ className, threadHeaderEnd }: StackChatPanelPro
void Promise.resolve(aui.threads().switchToNewThread()).catch(() => undefined);
}, [aui, isIdle]);
- if (settingsOpen) {
- return (
- <div className={cn('flex h-full min-h-0 flex-col', className)}>
- <TruefoundrySettingsBuilder />
- </div>
- );
- }
-
- if (view === 'list') {
- return (
- <div className={cn('flex h-full min-h-0 flex-col', className)}>
- <ThreadListContainer onThreadOpen={() => setView('thread')} />
- <footer className="flex shrink-0 justify-end border-t border-border px-2 py-1.5">
- <ShellActions />
- </footer>
- </div>
- );
- }
-
return (
<div className={cn('flex h-full min-h-0 flex-col', className)}>
- <header className="flex shrink-0 items-center gap-1 border-b border-border px-2 py-1.5">
- <button
- type="button"
- aria-label="Sessions"
- title="Sessions"
- className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
- onClick={() => setView('list')}
- >
- <Icon name="clock-rotate-left" />
- </button>
- <NamedAgentHeaderLabel />
- <span className="min-w-0 flex-1" />
- <ClearChatButton />
- <SaveAgentButton />
- <ShellActions />
- {threadHeaderEnd}
- </header>
- <div className="min-h-0 flex-1">{isIdle ? <SelectAgentEmptyState /> : <Thread />}</div>
+ {settingsOpen ? (
+ <div className="min-h-0 flex-1">
+ <TruefoundrySettingsBuilder />
+ </div>
+ ) : view === 'list' ? (
+ <ThreadListContainer onThreadOpen={() => setView('thread')} />
+ ) : (
+ <>
+ <header className="flex shrink-0 items-center gap-1 border-b border-border px-2 py-1.5">
+ <button
+ type="button"
+ aria-label="Sessions"
+ title="Sessions"
+ className={auiButtonClass({ variant: 'ghost', size: 'icon' })}
+ onClick={() => setView('list')}
+ >
+ <Icon name="clock-rotate-left" />
+ </button>
+ <NamedAgentHeaderLabel />
+ <span className="min-w-0 flex-1" />
+ <ClearChatButton />
+ <SaveAgentButton />
+ {threadHeaderEnd}
+ </header>
+ <div className="min-h-0 flex-1">{isIdle ? <SelectAgentEmptyState /> : <Thread />}</div>
+ </>
+ )}
+ {/* Stable mount: only ShellActions needs to survive Settings / list / thread; host end chrome stays in the thread header. */}
+ <footer className="flex shrink-0 justify-end border-t border-border px-2 py-1.5">
+ <ShellActions key="shell-actions" />
+ </footer>
</div>
);
}
diff --git a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
index 1e2b585aa..f2071d4f5 100644
--- a/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
+++ b/packages/trueforge-ui-sdk/src/theme/defaultSlots.ts
@@ -32,6 +32,7 @@ import { SandboxToolCallCard } from '../atoms/SandboxToolCallCard.js';
import { SaveAgentButton } from '../atoms/SaveAgentButton.js';
import { ScrollToBottomButton } from '../atoms/ScrollToBottomButton.js';
import { SelectAgentEmptyState } from '../atoms/SelectAgentEmptyState.js';
+import { ShellActionsActionSlot } from '../atoms/ShellActionsActionSlot.js';
import { MessageListSkeleton } from '../atoms/Skeletons.js';
import { SubAgentCard } from '../atoms/SubAgentCard.js';
import { SyntaxHighlighter } from '../atoms/SyntaxHighlighter.js';
@@ -123,4 +124,5 @@ export const defaultSlots = {
MessageGroup,
Toast,
ToastStack,
+ ShellActionsActionSlot,
} satisfies AtomSlots;
diff --git a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
index 4ea0727d8..94a3a4d67 100644
--- a/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
+++ b/packages/trueforge-ui-sdk/test/containers/TrueforgeUI.test.tsx
@@ -401,6 +401,10 @@ describe('layout slot overrides', () => {
return <button type="button">custom clear</button>;
}
+ function CustomActionSlot() {
+ return <button type="button">custom action</button>;
+ }
+
// dock and widget render their header through StackChatPanel.
const hosts = [
['sidebar', SidebarLayout],
@@ -424,6 +428,72 @@ describe('layout slot overrides', () => {
expect(screen.getByRole('button', { name: 'custom clear' })).toBeInTheDocument();
expect(screen.queryByRole('button', { name: 'Clear chat' })).not.toBeInTheDocument();
});
+
+ 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)',
+ (_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(screen.getAllByRole('button', { name: 'Settings' })[0]!);
+ expect(screen.getByRole('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', () => {
diff --git a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts b/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
index cc7e133a9..3b095cf68 100644
--- a/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
+++ b/packages/trueforge-ui-sdk/test/publicUiExports.test.ts
@@ -63,6 +63,7 @@ const expectedRuntimeExports: Array<keyof typeof sdk> = [
'ScrollToBottomButton',
'SelectAgentEmptyState',
'ServerProvider',
+ 'ShellActionsActionSlot',
'ShellModeProvider',
'SlotsProvider',
'SubAgentCard',