Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

feat(routes): add recovery option for V4 experience and update sidebar toggle logic (#19053)

marliessophie53fbc0dd59b8
diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.clienttest.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.clienttest.ts
index 8209766f73..5b638a8823 100644
--- a/web/src/components/layouts/app-layout/utils/navigationFilters.clienttest.ts
+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.clienttest.ts
@@ -1,6 +1,6 @@
import { testFeatureFlags } from "@/src/__tests__/fixtures/feature-flags";
import type { Session } from "next-auth";
-import type { Route } from "@/src/components/layouts/routes";
+import { ROUTES, type Route } from "@/src/components/layouts/routes";
import { applyNavigationFilters } from "./navigationFilters";
import type { NavigationFilterContext } from "./navigationFilters.types";
@@ -30,3 +30,44 @@ it("keeps Topics hidden without explicit opt-in despite admin and experimental o
context.session!.user!.featureFlags.langfuseTopics = true;
expect(applyNavigationFilters([route], context, undefined)).toEqual([route]);
});
+
+it.each([
+ { forceV3Experience: true, visible: false },
+ { forceV3Experience: false, visible: true },
+])(
+ "recovery visibility is $visible when forceV3Experience is $forceV3Experience",
+ ({ forceV3Experience, visible }) => {
+ const route = ROUTES.find(
+ (route) => route.featureFlag === "v4BetaToggleVisible",
+ )!;
+ const context: NavigationFilterContext = {
+ routerProjectId: "project-1",
+ routerOrganizationId: undefined,
+ session: {
+ user: {
+ canToggleV4: false,
+ v4BetaEnabled: false,
+ v4UpgradeUiAvailable: true,
+ featureFlags: testFeatureFlags({}),
+ },
+ environment: { v4WriteMode: "dual" },
+ } as Session,
+ enableExperimentalFeatures: false,
+ internalFeaturesEnabled: false,
+ cloudAdmin: false,
+ entitlements: [],
+ uiCustomization: null,
+ isLangfuseCloud: true,
+ hasActiveCloudIncident: false,
+ forceV3Experience,
+ currentPath: "/project/project-1",
+ };
+
+ expect(applyNavigationFilters([route], context, undefined)).toEqual(
+ visible ? [route] : [],
+ );
+
+ context.routerProjectId = undefined;
+ expect(applyNavigationFilters([route], context, undefined)).toEqual([]);
+ },
+);
diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
index 4e9ef11285..05326b2607 100644
--- a/web/src/components/layouts/app-layout/utils/navigationFilters.ts
+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.ts
@@ -16,6 +16,17 @@ type Organization =
| null
| undefined;
+function canRecoverV4(ctx: NavigationFilterContext): boolean {
+ return (
+ ctx.isLangfuseCloud &&
+ Boolean(ctx.routerProjectId) &&
+ ctx.forceV3Experience !== true &&
+ ctx.session?.environment?.v4WriteMode === "dual" &&
+ ctx.session?.user?.canToggleV4 === false &&
+ ctx.session?.user?.v4BetaEnabled === false
+ );
+}
+
/**
* Individual filter functions - each handles one concern
* Exported for testing and composition
@@ -95,7 +106,9 @@ const filters = {
}
if (route.featureFlag === "v4BetaToggleVisible") {
- return ctx.session?.user?.canToggleV4 === true ? route : null;
+ return ctx.session?.user?.canToggleV4 === true || canRecoverV4(ctx)
+ ? route
+ : null;
}
const hasFlag =
@@ -190,6 +203,7 @@ const filters = {
isLangfuseCloud: ctx.isLangfuseCloud,
hasActiveCloudIncident: ctx.hasActiveCloudIncident,
canToggleV4: ctx.session?.user?.canToggleV4 === true,
+ canRecoverV4: canRecoverV4(ctx),
forceV3Experience: ctx.forceV3Experience,
v4WriteMode: ctx.session?.environment?.v4WriteMode,
v4UpgradeUiAvailable: ctx.session?.user?.v4UpgradeUiAvailable === true,
diff --git a/web/src/components/layouts/app-layout/utils/navigationFilters.types.ts b/web/src/components/layouts/app-layout/utils/navigationFilters.types.ts
index 4858dcba44..a8f84ec0c5 100644
--- a/web/src/components/layouts/app-layout/utils/navigationFilters.types.ts
+++ b/web/src/components/layouts/app-layout/utils/navigationFilters.types.ts
@@ -28,7 +28,7 @@ export type NavigationFilterContext = {
isLangfuseCloud: boolean;
/** Whether Langfuse Cloud currently has a degraded or downtime incident */
hasActiveCloudIncident: boolean;
- /** Whether the current project must remain on the v3 experience */
+ /** Whether the current project must remain on v3. */
forceV3Experience: boolean;
internalFeaturesEnabled: boolean;
/** Current router path for active state detection */
diff --git a/web/src/components/layouts/routes.tsx b/web/src/components/layouts/routes.tsx
index df38f20b94..944d593784 100644
--- a/web/src/components/layouts/routes.tsx
+++ b/web/src/components/layouts/routes.tsx
@@ -75,6 +75,7 @@ export type Route = {
isLangfuseCloud: boolean;
hasActiveCloudIncident: boolean;
canToggleV4: boolean;
+ canRecoverV4: boolean;
forceV3Experience: boolean;
v4WriteMode: undefined | "legacy" | "dual" | "events_only"; // undefined until the session has loaded
v4UpgradeUiAvailable: boolean; // deployment shows the v4 migration UI (see isV4UpgradeUiAvailable)
@@ -259,9 +260,15 @@ export const ROUTES: Route[] = [
href: "",
section: RouteSection.Secondary,
featureFlag: "v4BetaToggleVisible",
- // v4-upgrade users get this toggle inside the migration panel instead.
- show: ({ canToggleV4, forceV3Experience, v4UpgradeUiAvailable }) =>
- canToggleV4 && (!v4UpgradeUiAvailable || forceV3Experience),
+ // Recovery stays in the sidebar; ordinary opt-in lives in the migration panel.
+ show: ({
+ canToggleV4,
+ canRecoverV4,
+ forceV3Experience,
+ v4UpgradeUiAvailable,
+ }) =>
+ canRecoverV4 ||
+ (canToggleV4 && (!v4UpgradeUiAvailable || forceV3Experience)),
menuNode: <V4SidebarToggle />,
},
{
diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsx
index 8632dfe6b5..fdc2c8a38d 100644
--- a/web/src/features/events/components/V4SidebarToggle.tsx
+++ b/web/src/features/events/components/V4SidebarToggle.tsx
@@ -164,6 +164,12 @@ function useV4PreviewToggle(source: "sidebar" | "migration_panel") {
}
export function V4SidebarToggle() {
+ const { canToggleV4 } = useReadPath();
+ // A locked toggle is only shown in the sidebar for one-way recovery.
+ const label = canToggleV4 ? V4_PREVIEW_LABEL : "Enable V4";
+ const description = canToggleV4
+ ? V4_PREVIEW_DESCRIPTION
+ : "Your account is using the legacy experience due to a configuration issue. Enable V4 to return to the default experience. This is a personal setting across all your projects.";
const {
isChecked,
isLoading,
@@ -173,6 +179,10 @@ export function V4SidebarToggle() {
dismissIntroDialog,
} = useV4PreviewToggle("sidebar");
+ const handleSidebarToggle = (enabled: boolean) => {
+ if (canToggleV4 || enabled) handleToggle(enabled);
+ };
+
return (
<>
<SidebarMenuButton
@@ -185,9 +195,9 @@ export function V4SidebarToggle() {
<Label
htmlFor="v4-beta-toggle"
className="block min-w-0 flex-1 cursor-pointer truncate text-sm font-normal"
- title={V4_PREVIEW_LABEL}
+ title={label}
>
- {V4_PREVIEW_LABEL}
+ {label}
</Label>
</div>
<Tooltip>
@@ -197,19 +207,19 @@ export function V4SidebarToggle() {
id="v4-beta-toggle"
size="sm"
checked={isChecked}
- onCheckedChange={handleToggle}
+ onCheckedChange={handleSidebarToggle}
disabled={isLoading}
- aria-label="Toggle V4 Preview"
+ aria-label={canToggleV4 ? "Toggle V4 Preview" : "Enable V4"}
aria-describedby="v4-preview-sidebar-description"
/>
</div>
</TooltipTrigger>
<TooltipContent side="right" className="max-w-xs text-xs">
- {V4_PREVIEW_DESCRIPTION}
+ {description}
</TooltipContent>
</Tooltip>
<span id="v4-preview-sidebar-description" className="sr-only">
- {V4_PREVIEW_DESCRIPTION}
+ {description}
</span>
</div>
</SidebarMenuButton>
diff --git a/web/src/server/api/routers/userAccount.ts b/web/src/server/api/routers/userAccount.ts
index 8e5da7b07d..a4f666e2d7 100644
--- a/web/src/server/api/routers/userAccount.ts
+++ b/web/src/server/api/routers/userAccount.ts
@@ -348,7 +348,8 @@ export const userAccountRouter = createTRPCRouter({
{ isLangfuseCloudAdmin: ctx.session.user.admin === true },
);
- if (!userCanToggleV4) {
+ // Rollout-locked users may recover a missing opt-in, but cannot opt out.
+ if (!userCanToggleV4 && !input.enabled) {
return {
success: true,
v4BetaEnabled: userRolloutState.v4BetaEnabled,
@@ -364,7 +365,7 @@ export const userAccountRouter = createTRPCRouter({
return {
success: true,
v4BetaEnabled: input.enabled,
- canToggleV4: true,
+ canToggleV4: userCanToggleV4,
};
}),
});