πͺ’ Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat: introduce forced v3 experience for projects integrating through 3rd party providers on legacy SDKs (#16046)
marliessophie0f720df3164b
diff --git a/packages/shared/src/env.ts b/packages/shared/src/env.tsindex c17cd7ca9d..f92e4e7e78 100644--- a/packages/shared/src/env.ts+++ b/packages/shared/src/env.ts@@ -226,6 +226,11 @@ const EnvSchema = z.object({.string().optional().transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),+ // Has no effect in events_only mode, where the v3 experience cannot work.+ LANGFUSE_FORCE_V3_EXPERIENCE: z+ .string()+ .optional()+ .transform((s) => (s ? s.split(",").map((id) => id.trim()) : [])),SALT: z.string().optional(), // used by components imported by web packageLANGFUSE_LOG_LEVEL: z.enum(["trace", "debug", "info", "warn", "error", "fatal"])diff --git a/packages/shared/src/server/forceV3Experience.ts b/packages/shared/src/server/forceV3Experience.tsnew file mode 100644index 0000000000..3165e7c7bc--- /dev/null+++ b/packages/shared/src/server/forceV3Experience.ts@@ -0,0 +1,12 @@+import { env } from "../env";++/**+ * Projects listed in LANGFUSE_FORCE_V3_EXPERIENCE keep the legacy (v3)+ * experience: the old eval experience (trace-level evaluator create/update+ * stays available) and none of the v4 migration/upgrade UI. Set only on Cloud+ * for projects instrumented via integration partners that have not upgraded to+ * OTEL ingestion yet.+ */+export function isForceV3ExperienceProject(projectId: string): boolean {+ return env.LANGFUSE_FORCE_V3_EXPERIENCE.includes(projectId);+}diff --git a/packages/shared/src/server/index.ts b/packages/shared/src/server/index.tsindex 814d0232af..3f9d7434e4 100644--- a/packages/shared/src/server/index.ts+++ b/packages/shared/src/server/index.ts@@ -173,6 +173,7 @@ export * from "./utils/headerUtils";export * from "./utils/formatAuthProvider";export * from "./traceDeletionProcessor";export * from "./deletionGuard";+export * from "./forceV3Experience";export * from "./analytics-integrations/types";// Re-annotate these deprecated routing wrappers at the public server barrel.diff --git a/web/src/__tests__/server/evals-trpc.servertest.ts b/web/src/__tests__/server/evals-trpc.servertest.tsindex ab1e6b0414..9b0d3ff1c1 100644--- a/web/src/__tests__/server/evals-trpc.servertest.ts+++ b/web/src/__tests__/server/evals-trpc.servertest.ts@@ -1,14 +1,19 @@import { beforeEach, vi } from "vitest";import type * as SharedEnvModule from "@langfuse/shared/src/env";-const { runCodeEvalTestForJobConfigMock } = vi.hoisted(() => {- process.env.LANGFUSE_CODE_EVAL_DISPATCHER = "insecure-local";- process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN = "true";-- return {- runCodeEvalTestForJobConfigMock: vi.fn(),- };-});+const { runCodeEvalTestForJobConfigMock, forceV3ProjectIds } = vi.hoisted(+ () => {+ process.env.LANGFUSE_CODE_EVAL_DISPATCHER = "insecure-local";+ process.env.LANGFUSE_MIGRATION_V4_ALLOW_PREVIEW_OPT_IN = "true";++ return {+ runCodeEvalTestForJobConfigMock: vi.fn(),+ // Mutable backing for the mocked LANGFUSE_FORCE_V3_EXPERIENCE list so+ // individual tests can force a project onto the v3 experience.+ forceV3ProjectIds: { current: [] as string[] },+ };+ },+);vi.mock("@langfuse/shared/src/env", async (importOriginal) => {const actual = await importOriginal<typeof SharedEnvModule>();@@ -19,6 +24,9 @@ vi.mock("@langfuse/shared/src/env", async (importOriginal) => {...actual.env,LANGFUSE_CODE_EVAL_DISPATCHER: "insecure-local",NEXT_PUBLIC_LANGFUSE_CLOUD_REGION: undefined,+ get LANGFUSE_FORCE_V3_EXPERIENCE() {+ return forceV3ProjectIds.current;+ },},};});@@ -56,6 +64,7 @@ import type { Session } from "next-auth";import { env } from "@/src/env.mjs";beforeEach(() => {+ forceV3ProjectIds.current = [];runCodeEvalTestForJobConfigMock.mockReset();runCodeEvalTestForJobConfigMock.mockResolvedValue({success: true,@@ -1047,25 +1056,34 @@ describe("evals trpc", () => {},});- await expect(- caller.evals.createJob({- projectId: project.id,- evalTemplateId: evalTemplate.id,- scoreName: "bad-trace-score",- target: EvalTargetObject.TRACE,- filter: [],- mapping: [- {- templateVariable: "input",- selectedColumnId: "input",- jsonSelector: null,- },- ],- sampling: 1,- delay: 0,- timeScope: ["NEW"],- }),- ).rejects.toThrow("Variable mapping does not match evaluator target.");+ // Open the legacy-target gate (the .env test config is Cloud + dual) so+ // this test reaches the variable-mapping validation behind it.+ const originalWriteMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "legacy");++ try {+ await expect(+ caller.evals.createJob({+ projectId: project.id,+ evalTemplateId: evalTemplate.id,+ scoreName: "bad-trace-score",+ target: EvalTargetObject.TRACE,+ filter: [],+ mapping: [+ {+ templateVariable: "input",+ selectedColumnId: "input",+ jsonSelector: null,+ },+ ],+ sampling: 1,+ delay: 0,+ timeScope: ["NEW"],+ }),+ ).rejects.toThrow("Variable mapping does not match evaluator target.");+ } finally {+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalWriteMode);+ }await expect(prisma.jobConfiguration.findFirst({@@ -1093,29 +1111,122 @@ describe("evals trpc", () => {},});- await expect(- caller.evals.createJob({- projectId: project.id,- evalTemplateId: evalTemplate.id,- scoreName: "bad-trace-filter",- target: EvalTargetObject.TRACE,- filter: [- {- type: "numberObject",- column: "Scores (numeric)",- key: "accuracy",- operator: ">",- value: 0.8,- },- ],- mapping: [],- sampling: 1,- delay: 0,- timeScope: ["NEW"],- }),- ).rejects.toThrow(- 'Filter column "Scores (numeric)" is not supported for target "trace".',- );+ // Open the legacy-target gate (the .env test config is Cloud + dual) so+ // this test reaches the filter validation behind it.+ const originalWriteMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "legacy");++ try {+ await expect(+ caller.evals.createJob({+ projectId: project.id,+ evalTemplateId: evalTemplate.id,+ scoreName: "bad-trace-filter",+ target: EvalTargetObject.TRACE,+ filter: [+ {+ type: "numberObject",+ column: "Scores (numeric)",+ key: "accuracy",+ operator: ">",+ value: 0.8,+ },+ ],+ mapping: [],+ sampling: 1,+ delay: 0,+ timeScope: ["NEW"],+ }),+ ).rejects.toThrow(+ 'Filter column "Scores (numeric)" is not supported for target "trace".',+ );+ } finally {+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalWriteMode);+ }+ });+ });++ describe("evals.createJob legacy target gate", () => {+ const createTraceTemplate = (projectId: string) =>+ prisma.evalTemplate.create({+ data: {+ projectId,+ name: `trace-gate-template-${projectId}`,+ version: 1,+ prompt: "Score {{input}}",+ vars: ["input"],+ outputDefinition: createNumericEvalOutputDefinition({+ reasoningDescription: "Why",+ scoreDescription: "How good",+ }),+ },+ });++ const traceMapping = [+ {+ templateVariable: "input",+ langfuseObject: "trace",+ objectName: null,+ selectedColumnId: "input",+ jsonSelector: null,+ },+ ];++ it("rejects new trace-target evaluators when the legacy experience is disabled", async () => {+ const { project, caller } = await prepare();+ const originalMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "events_only");++ try {+ const template = await createTraceTemplate(project.id);+ await expect(+ caller.evals.createJob({+ projectId: project.id,+ evalTemplateId: template.id,+ scoreName: "gate-closed-score",+ target: EvalTargetObject.TRACE,+ filter: [],+ mapping: traceMapping,+ sampling: 1,+ delay: 0,+ timeScope: ["NEW"],+ }),+ ).rejects.toThrow("Trace- and dataset-level evaluators are no longer");++ await expect(+ prisma.jobConfiguration.findFirst({+ where: { projectId: project.id, scoreName: "gate-closed-score" },+ }),+ ).resolves.toBeNull();+ } finally {+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalMode);+ }+ });++ it("rejects new trace-target evaluators for force-v3 projects in events_only mode", async () => {+ const { project, caller } = await prepare();+ const originalMode = env.LANGFUSE_MIGRATION_V4_WRITE_MODE;+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", "events_only");+ forceV3ProjectIds.current = [project.id];++ try {+ const template = await createTraceTemplate(project.id);+ await expect(+ caller.evals.createJob({+ projectId: project.id,+ evalTemplateId: template.id,+ scoreName: "gate-forced-score",+ target: EvalTargetObject.TRACE,+ filter: [],+ mapping: traceMapping,+ sampling: 1,+ delay: 0,+ timeScope: ["NEW"],+ }),+ ).rejects.toThrow("Trace- and dataset-level evaluators are no longer");+ } finally {+ Reflect.set(env, "LANGFUSE_MIGRATION_V4_WRITE_MODE", originalMode);+ }});});diff --git a/web/src/__tests__/server/unit/legacyEvalGate.servertest.ts b/web/src/__tests__/server/unit/legacyEvalGate.servertest.tsnew file mode 100644index 0000000000..0a4fa1acdf--- /dev/null+++ b/web/src/__tests__/server/unit/legacyEvalGate.servertest.ts@@ -0,0 +1,62 @@+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";++describe("isNewLegacyEvalAllowed", () => {+ it("blocks new legacy evals in events_only mode", () => {+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode: "events_only",+ isLangfuseCloud: false,+ isForceV3Project: false,+ }),+ ).toBe(false);+ });++ it("blocks new legacy evals on Cloud in dual mode", () => {+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode: "dual",+ isLangfuseCloud: true,+ isForceV3Project: false,+ }),+ ).toBe(false);+ });++ it("allows new legacy evals on self-hosted dual and legacy modes", () => {+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode: "dual",+ isLangfuseCloud: false,+ isForceV3Project: false,+ }),+ ).toBe(true);+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode: "legacy",+ isLangfuseCloud: false,+ isForceV3Project: false,+ }),+ ).toBe(true);+ });++ it("allows new legacy evals for forced-v3 projects while legacy writes exist", () => {+ for (const v4WriteMode of ["dual", "legacy"] as const) {+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode,+ isLangfuseCloud: true,+ isForceV3Project: true,+ }),+ ).toBe(true);+ }+ });++ it("blocks forced-v3 projects in events_only mode", () => {+ expect(+ isNewLegacyEvalAllowed({+ v4WriteMode: "events_only",+ isLangfuseCloud: true,+ isForceV3Project: true,+ }),+ ).toBe(false);+ });+});diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.tsindex 1a40f60845..980e82b211 100644--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts@@ -10,6 +10,7 @@ vi.mock("@/src/server/auth", () => ({const sharedServerMock = vi.hoisted(() => ({queryClickhouse: vi.fn(),+ isForceV3ExperienceProject: vi.fn(() => false),logger: {warn: vi.fn(),},@@ -823,6 +824,7 @@ describe("v4TransitionRouter", () => {mixpanel: false,blobStorage: false,},+ forceV3Experience: false,},{projectId: secondProjectId,@@ -833,6 +835,7 @@ describe("v4TransitionRouter", () => {mixpanel: true,blobStorage: false,},+ forceV3Experience: false,},],});@@ -1005,6 +1008,7 @@ describe("v4TransitionRouter", () => {mixpanel: false,blobStorage: false,},+ forceV3Experience: false,},],});diff --git a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsxindex 4d04ba1c77..af0717d25e 100644--- a/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx+++ b/web/src/components/layouts/app-layout/variants/AuthenticatedLayout.tsx@@ -316,7 +316,7 @@ function ConnectedAppSidebar({}) {const { isMobile } = useSidebar();const uiCustomization = useUiCustomization();- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(routerProjectId);const plan = usePlan();const capture = usePostHogClientCapture();const session = useSession();diff --git a/web/src/features/evals/components/eval-version-callout.tsx b/web/src/features/evals/components/eval-version-callout.tsxindex f1c3cd1a94..f8cc1a452c 100644--- a/web/src/features/evals/components/eval-version-callout.tsx+++ b/web/src/features/evals/components/eval-version-callout.tsx@@ -83,6 +83,12 @@ const getCalloutContent = (// For dataset target (legacy dataset run methods)if (isDatasetTarget(targetObject)) {+ // Forced-v3 projects keep trace evaluators as their intended experience β+ // no upgrade nag.+ if (evalCapabilities.forceV3Experience) {+ return hidden;+ }+return {visible: true,title: "Legacy low-level SDK methods",@@ -108,6 +114,12 @@ const getCalloutContent = (// For trace targetif (isTraceTarget(targetObject)) {+ // Forced-v3 projects keep trace evaluators as their intended experience β+ // no upgrade nag.+ if (evalCapabilities.forceV3Experience) {+ return hidden;+ }+return {visible: true,title: "Consider upgrading to observation evaluators",diff --git a/web/src/features/evals/components/evaluator-table.tsx b/web/src/features/evals/components/evaluator-table.tsxindex 5b101271fb..60fc1d920a 100644--- a/web/src/features/evals/components/evaluator-table.tsx+++ b/web/src/features/evals/components/evaluator-table.tsx@@ -74,7 +74,7 @@ function DeprecatedChipCell() {export default function EvaluatorTable({ projectId }: { projectId: string }) {const router = useRouter();const capture = usePostHogClientCapture();- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);const { setDetailPageList } = useDetailPageLists();const [paginationState, setPaginationState] = usePaginationState(0, 50, {page: "pageIndex",diff --git a/web/src/features/evals/components/inner-evaluator-form.tsx b/web/src/features/evals/components/inner-evaluator-form.tsxindex 3082a1db69..7aa671c89b 100644--- a/web/src/features/evals/components/inner-evaluator-form.tsx+++ b/web/src/features/evals/components/inner-evaluator-form.tsx@@ -94,6 +94,7 @@ import {isExperimentTarget,isLegacyEvalTarget,isTraceTarget,+ shouldShowLegacyTracePreview,} from "@/src/features/evals/utils/typeHelpers";import {useUserFacingTarget,@@ -1252,7 +1253,12 @@ export const InnerEvaluatorForm = (props: {{/* Preview based on target type */}{previewTableVisible && (<>- {isTraceTarget(form.watch("target")) && (+ {/* The traces preview reads the legacy traces table, which+ is not the v4 user's experience β never show it there. */}+ {shouldShowLegacyTracePreview(+ form.watch("target"),+ isBetaEnabled,+ ) && (<TracesPreviewprojectId={props.projectId}filterState={watchedFilter}diff --git a/web/src/features/evals/components/variable-mapping-card.tsx b/web/src/features/evals/components/variable-mapping-card.tsxindex 439fb473e4..af49d86a59 100644--- a/web/src/features/evals/components/variable-mapping-card.tsx+++ b/web/src/features/evals/components/variable-mapping-card.tsx@@ -32,8 +32,8 @@ import {isEventTarget,isExperimentTarget,isLegacyEvalTarget,- isTraceTarget,isTraceOrDatasetObject,+ shouldShowLegacyTracePreview,} from "@/src/features/evals/utils/typeHelpers";import {FormControl,@@ -98,8 +98,10 @@ export const VariableMappingCard = ({typeof router.query.peek === "string" ? router.query.peek : undefined;const isPeekView = Boolean(peekId);const target = form.watch("target");+ // The trace preview reads the legacy traces table, which is not the v4+ // user's experience β never offer it there.const shouldShowPreviewForTarget =- isTraceTarget(target) ||+ shouldShowLegacyTracePreview(target, isBetaEnabled) ||isEventTarget(target) ||(isExperimentTarget(target) && isBetaEnabled);@@ -241,12 +243,13 @@ export const VariableMappingCard = ({)}</div></div>- {isTraceTarget(form.watch("target")) && !disabled && (- <FormDescription>- Preview of the evaluation prompt with the variables replaced with the- first matched trace data subject to the filters.- </FormDescription>- )}+ {shouldShowLegacyTracePreview(form.watch("target"), isBetaEnabled) &&+ !disabled && (+ <FormDescription>+ Preview of the evaluation prompt with the variables replaced with+ the first matched trace data subject to the filters.+ </FormDescription>+ )}<div className="flex max-w-full flex-col gap-4"><FormFieldcontrol={form.control}@@ -259,7 +262,10 @@ export const VariableMappingCard = ({!shouldWrapVariables && "lg:flex-row",)}>- {showPreview ? (+ {/* Derive eligibility at render time: showPreview is state set+ by an effect and must never override target eligibility+ (e.g. trace targets on v4 have no preview data source). */}+ {showPreview && shouldShowPreviewControls ? (previewData ? (<EvaluationPromptPreviewprojectId={projectId}diff --git a/web/src/features/evals/hooks/useEvalCapabilities.ts b/web/src/features/evals/hooks/useEvalCapabilities.tsindex 7a0ff2697c..8c1fb288e2 100644--- a/web/src/features/evals/hooks/useEvalCapabilities.ts+++ b/web/src/features/evals/hooks/useEvalCapabilities.ts@@ -3,6 +3,8 @@ import { api } from "@/src/utils/api";import { useLangfuseCloudRegion } from "@/src/features/organizations/hooks";import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";import { useIsCodeEvalEnabled } from "@/src/features/evals/hooks/useIsCodeEvalEnabled";+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";export interface EvalCapabilities {isNewCompatible: boolean;@@ -10,6 +12,7 @@ export interface EvalCapabilities {allowLegacy: boolean;isLoading: boolean;hasLegacyEvals: boolean;+ forceV3Experience: boolean;}/**@@ -35,7 +38,7 @@ export function useEvalCapabilities(// Query SDK version info from events table (only when v4 beta is enabled)const sdkVersionInfo = api.events.getSdkVersionInfo.useQuery({ projectId },- { enabled: isBetaEnabled },+ { enabled: isBetaEnabled && Boolean(projectId) },);// Determine OTEL status from SDK version info@@ -44,9 +47,7 @@ export function useEvalCapabilities(// Get eval counts including legacy eval countconst evalCounts = api.evals.counts.useQuery({ projectId },- {- enabled: !!projectId,- },+ { enabled: Boolean(projectId) },);const hasLegacyEvals = (evalCounts.data?.legacyConfigCount ?? 0) > 0;@@ -56,18 +57,15 @@ export function useEvalCapabilities(const { isLangfuseCloud } = useLangfuseCloudRegion();const v4WriteMode = session?.environment?.v4WriteMode;- // Whether a *new* config may use the legacy experience:- // - events_only: legacy tables are no longer written β no new legacy evals.- // - dual: self-hosted deployments always allow legacy; on Cloud, no new- // legacy evals β existing legacy evaluators stay visible in read-only mode,- // but cannot be newly set up.- // - legacy: legacy is the only experience.- const modeAllowsNewLegacy =- v4WriteMode === "events_only"- ? false- : v4WriteMode === "dual"- ? !isLangfuseCloud- : v4WriteMode === "legacy"; // legacy β true; undefined (loading) β false+ // Projects forced onto v3 keep legacy evals while legacy tables are written.+ const forceV3Experience = useForceV3Experience(projectId);++ // Whether a *new* config may use the legacy experience.+ const modeAllowsNewLegacy = isNewLegacyEvalAllowed({+ v4WriteMode,+ isLangfuseCloud,+ isForceV3Project: forceV3Experience,+ });return {isNewCompatible: isOtel,@@ -80,5 +78,6 @@ export function useEvalCapabilities(isLoading:evalCounts.isLoading || isSessionLoading || sdkVersionInfo.isLoading,hasLegacyEvals,+ forceV3Experience,};}diff --git a/web/src/features/evals/hooks/useEvalConfigMappingData.ts b/web/src/features/evals/hooks/useEvalConfigMappingData.tsindex e4fd0a4468..ecc76340cc 100644--- a/web/src/features/evals/hooks/useEvalConfigMappingData.ts+++ b/web/src/features/evals/hooks/useEvalConfigMappingData.ts@@ -8,6 +8,7 @@ import {} from "@/src/features/evals/hooks/usePreviewData";import { useEffect, useRef } from "react";import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";+import { isTraceTargetOnV4 } from "@/src/features/evals/utils/typeHelpers";import {type EvalPreviewPointer,getEvalPreviewPointerFromUrlQuery,@@ -42,9 +43,13 @@ export function useEvalConfigMappingData(const previewPointer =selectedPreviewPointer ?? urlPreviewPointer ?? firstPreviewPointer;+ // The trace preview reads the legacy traces table, which is not the v4+ // user's experience β never fetch or expect preview data there.+ const traceTargetOnV4 = isTraceTargetOnV4(targetValue, isBetaEnabled);+const { previewData, isLoading } = usePreviewData({projectId,- enabled: !disabled && Boolean(previewPointer),+ enabled: !disabled && !traceTargetOnV4 && Boolean(previewPointer),target: targetValue,traceId: previewPointer?.traceId,observationId: previewPointer?.observationId,diff --git a/web/src/features/evals/pages/remap-evaluator.tsx b/web/src/features/evals/pages/remap-evaluator.tsxindex 88b7400c3f..003e75c0fe 100644--- a/web/src/features/evals/pages/remap-evaluator.tsx+++ b/web/src/features/evals/pages/remap-evaluator.tsx@@ -47,7 +47,7 @@ export default function RemapEvaluatorPage() {const router = useRouter();const projectId = router.query.projectId as string;const evalConfigId = router.query.evaluator as string;- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(projectId);const capture = usePostHogClientCapture();const { organization } = useQueryProject();const canUseAssistant = useCanUseInAppAgent();diff --git a/web/src/features/evals/server/legacyEvalGate.ts b/web/src/features/evals/server/legacyEvalGate.tsnew file mode 100644index 0000000000..647fb90711--- /dev/null+++ b/web/src/features/evals/server/legacyEvalGate.ts@@ -0,0 +1,31 @@+import { env } from "@/src/env.mjs";+import { InvalidRequestError } from "@langfuse/shared";+import { isForceV3ExperienceProject } from "@langfuse/shared/src/server";+import { isLegacyEvalTarget } from "@/src/features/evals/utils/typeHelpers";+import { isNewLegacyEvalAllowed } from "@/src/features/evals/utils/legacyEvalGate";++/**+ * Server-side guard mirroring the UI capability hook: reject creating a *new*+ * legacy-target (trace/dataset) evaluator on deployments where the legacy+ * experience is disabled. Forced-v3 projects are exempt unless events_only is+ * set. Non-legacy targets and updates to existing evaluators are unaffected.+ */+export function assertCanCreateLegacyEvalJob(params: {+ projectId: string;+ target: string;+}): void {+ const { projectId, target } = params;+ if (!isLegacyEvalTarget(target)) return;++ const allowed = isNewLegacyEvalAllowed({+ v4WriteMode: env.LANGFUSE_MIGRATION_V4_WRITE_MODE,+ isLangfuseCloud: Boolean(env.NEXT_PUBLIC_LANGFUSE_CLOUD_REGION),+ isForceV3Project: isForceV3ExperienceProject(projectId),+ });++ if (!allowed) {+ throw new InvalidRequestError(+ "Trace- and dataset-level evaluators are no longer available. Create an observation- or experiment-level evaluator instead.",+ );+ }+}diff --git a/web/src/features/evals/server/router.ts b/web/src/features/evals/server/router.tsindex 7fa3f5797b..ad05bf96b0 100644--- a/web/src/features/evals/server/router.ts+++ b/web/src/features/evals/server/router.ts@@ -97,6 +97,7 @@ import {prepareVariableMappingForEvaluatorUpgrade,} from "@/src/features/evals/server/evaluatorUpgrade";import { deleteJobConfigurationWithExecutions } from "@/src/features/evals/server/evaluatorRepository";+import { assertCanCreateLegacyEvalJob } from "@/src/features/evals/server/legacyEvalGate";export { CreateEvalTemplateInputSchema } from "@/src/features/evals/server/evalTemplateCreation";// Filter columns that used to be backed by the Postgres `traces` and@@ -1004,6 +1005,11 @@ export const evalRouter = createTRPCRouter({scope: "evalJob:CUD",});+ assertCanCreateLegacyEvalJob({+ projectId: input.projectId,+ target: input.target,+ });+const evalTemplate = await ctx.prisma.evalTemplate.findFirst({where: {id: input.evalTemplateId,diff --git a/web/src/features/evals/utils/legacyEvalGate.ts b/web/src/features/evals/utils/legacyEvalGate.tsnew file mode 100644index 0000000000..c965d8c5c7--- /dev/null+++ b/web/src/features/evals/utils/legacyEvalGate.ts@@ -0,0 +1,23 @@+/**+ * Pure decision shared by the client capability hook (`useEvalCapabilities`)+ * and the server create-gate (`assertCanCreateLegacyEvalJob`): may a *new*+ * evaluator use the legacy (trace/dataset) experience?+ *+ * - events_only: legacy tables are no longer written β no new legacy evals.+ * - dual: self-hosted deployments always allow legacy; on Cloud, no new legacy.+ * - legacy: legacy is the only experience.+ * - forced-v3 projects keep the legacy experience unless events_only is set.+ * - undefined write mode (session still loading client-side) β not allowed,+ * which keeps legacy options hidden until the mode is known.+ */+export function isNewLegacyEvalAllowed(params: {+ v4WriteMode: "legacy" | "dual" | "events_only" | undefined;+ isLangfuseCloud: boolean;+ isForceV3Project: boolean;+}): boolean {+ const { v4WriteMode, isLangfuseCloud, isForceV3Project } = params;+ if (v4WriteMode === "events_only") return false;+ if (isForceV3Project) return true;+ if (v4WriteMode === "dual") return !isLangfuseCloud;+ return v4WriteMode === "legacy";+}diff --git a/web/src/features/evals/utils/typeHelpers.ts b/web/src/features/evals/utils/typeHelpers.tsindex 2608987b69..eb394d91bc 100644--- a/web/src/features/evals/utils/typeHelpers.ts+++ b/web/src/features/evals/utils/typeHelpers.ts@@ -54,6 +54,18 @@ export const isTraceTarget = (targetObject: string): boolean => {return targetObject === EvalTargetObject.TRACE;};+export const isTraceTargetOnV4 = (+ targetObject: string,+ isBetaEnabled: boolean,+): boolean => isTraceTarget(targetObject) && isBetaEnabled;++export const shouldShowLegacyTracePreview = (+ targetObject: string,+ isBetaEnabled: boolean,+): boolean =>+ isTraceTarget(targetObject) &&+ !isTraceTargetOnV4(targetObject, isBetaEnabled);+export const isEventTarget = (targetObject: string): boolean => {return targetObject === EvalTargetObject.EVENT;};diff --git a/web/src/features/events/components/V4SidebarToggle.tsx b/web/src/features/events/components/V4SidebarToggle.tsxindex 8724d363bc..6eca7de72e 100644--- a/web/src/features/events/components/V4SidebarToggle.tsx+++ b/web/src/features/events/components/V4SidebarToggle.tsx@@ -10,6 +10,7 @@ import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";import { V4IntroDialog } from "@/src/features/events/components/V4IntroDialog";import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";+import { useQueryProject } from "@/src/features/projects/hooks";import { ZapIcon } from "lucide-react";import { useId } from "react";import { useRouter } from "next/router";@@ -127,7 +128,8 @@ export function V4SidebarToggle() {confirmIntroDialog,dismissIntroDialog,} = useV4PreviewToggle("sidebar");- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const { project } = useQueryProject();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);// v4-upgrade users get this toggle inside the migration panel instead.if (!canToggleV4 || v4UpgradeUiEnabled) {diff --git a/web/src/features/support-chat/SupportFormSection.tsx b/web/src/features/support-chat/SupportFormSection.tsxindex 9f0588ff84..0b06a46944 100644--- a/web/src/features/support-chat/SupportFormSection.tsx+++ b/web/src/features/support-chat/SupportFormSection.tsx@@ -198,7 +198,7 @@ export function SupportFormSection({const [sev1ConfirmOpen, setSev1ConfirmOpen] = useState(false);const { initialTopic } = useSupportDrawer();- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);const productFeatureTopics = TopicGroups["Product Features"].filter((topic) => topic !== "V4 Migration" || v4UpgradeUiEnabled,);diff --git a/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx b/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsxindex 315f63d115..718ed74893 100644--- a/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationBanner.clienttest.tsx@@ -61,6 +61,7 @@ const status = (experiments: { status: "loaded", result: "not_required" },apis: { status: "loaded", count: 0 },exports: { status: "loaded", count: 0 },+ forceV3Experience: false,...overrides,});diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsxindex 5cb6abd5ef..23bf91af93 100644--- a/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.clienttest.tsx@@ -1,4 +1,4 @@-import { render, screen } from "@testing-library/react";+import { fireEvent, render, screen } from "@testing-library/react";import { beforeEach, describe, expect, it, vi } from "vitest";import { V4MigrationDelayBadge } from "./V4MigrationDelayBadge";@@ -58,11 +58,22 @@ const mocks = vi.hoisted(() => ({delayedOtelIngestionCount: 0,} as V4MigrationSdkState,v4UpgradeUiEnabled: true,+ forceV3: false,+ isBetaEnabled: false,openMigrationPanel: vi.fn(),}));vi.mock("@/src/features/v4-migration/useV4UpgradeUiEnabled", () => ({useV4UpgradeUiEnabled: () => mocks.v4UpgradeUiEnabled,+ useV4UpgradeUiFlag: () => mocks.v4UpgradeUiEnabled,+}));++vi.mock("@/src/features/v4-migration/useForceV3Experience", () => ({+ useForceV3Experience: () => mocks.forceV3,+}));++vi.mock("@/src/features/events/hooks/useV4Beta", () => ({+ useV4Beta: () => ({ isBetaEnabled: mocks.isBetaEnabled }),}));vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({@@ -120,6 +131,8 @@ describe("V4MigrationDelayBadge", () => {beforeEach(() => {vi.clearAllMocks();mocks.v4UpgradeUiEnabled = true;+ mocks.forceV3 = false;+ mocks.isBetaEnabled = false;setSdk("latest", [makeSdkUsageSeries({})]);});@@ -192,4 +205,34 @@ describe("V4MigrationDelayBadge", () => {render(<V4MigrationDelayBadge />);expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();});++ it("stays hidden for forced-v3 projects while they view v3", () => {+ // On v3 views the legacy tables are real-time β no delay to announce.+ mocks.forceV3 = true;+ mocks.isBetaEnabled = false;+ setSdk("legacy", [outdatedSdkSeries()]);+ render(<V4MigrationDelayBadge />);+ expect(screen.queryByText("New data in ~15 min")).not.toBeInTheDocument();+ });++ it("opens the partner FAQ instead of the panel for forced-v3 projects on v4", () => {+ mocks.forceV3 = true;+ mocks.isBetaEnabled = true;+ setSdk("legacy", [outdatedSdkSeries()]);+ const windowOpen = vi.spyOn(window, "open").mockImplementation(() => null);++ render(<V4MigrationDelayBadge />);+ expect(+ screen.getAllByText(/Learn more in the docs/).length,+ ).toBeGreaterThan(0);++ fireEvent.click(screen.getAllByText("New data in ~15 min")[0]);+ expect(windowOpen).toHaveBeenCalledWith(+ expect.stringContaining("langfuse.com"),+ "_blank",+ "noopener,noreferrer",+ );+ expect(mocks.openMigrationPanel).not.toHaveBeenCalled();+ windowOpen.mockRestore();+ });});diff --git a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx b/web/src/features/v4-migration/V4MigrationDelayBadge.tsxindex 5928879467..e86eac035c 100644--- a/web/src/features/v4-migration/V4MigrationDelayBadge.tsx+++ b/web/src/features/v4-migration/V4MigrationDelayBadge.tsx@@ -1,5 +1,11 @@import { useState } from "react";-import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";+import { useRouter } from "next/router";+import {+ useV4UpgradeUiEnabled,+ useV4UpgradeUiFlag,+} from "@/src/features/v4-migration/useV4UpgradeUiEnabled";+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useQueryProject } from "@/src/features/projects/hooks";import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";@@ -15,17 +21,23 @@ import {} from "@/src/features/v4-migration/sdkVersionStatus";import { EvaluatorMigrationDialog } from "@/src/features/v4-migration/EvaluatorMigrationDialog";import { buildDeprecatedEvaluatorsUrl } from "@/src/features/v4-migration/evaluatorMigrationUrls";-import { useRouter } from "next/router";+import { useV4Beta } from "@/src/features/events/hooks/useV4Beta";export function V4MigrationDelayBadge() {- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiFlagEnabled = useV4UpgradeUiFlag();const openMigrationPanel = useOpenV4MigrationPanel();const { project, organization } = useQueryProject();+ const forceV3 = useForceV3Experience(project?.id);+ const { isBetaEnabled } = useV4Beta();const capture = usePostHogClientCapture();++ // Forced-v3 projects still see the data-delay badge, but it points at the+ // partner FAQ instead of the migration panel+ const enabled = v4UpgradeUiFlagEnabled && (!forceV3 || isBetaEnabled);const sdk = useProjectV4SdkData({projectId: project?.id,orgId: organization?.id,- enabled: v4UpgradeUiEnabled && Boolean(project),+ enabled: enabled && Boolean(project),});// Every delayed ingestion path shows the pill, matching the migration@@ -45,11 +57,16 @@ export function V4MigrationDelayBadge() {customActionable,].filter(Boolean).length;- if (!v4UpgradeUiEnabled || !project || actionablePaths === 0) {+ if (!enabled || !project || actionablePaths === 0) {return null;}const handleClick = () => {+ if (forceV3) {+ capture("v4_migration:delay_badge_clicked", { action: "docs" });+ window.open(PARTNER_INTEGRATION_FAQ_URL, "_blank", "noopener,noreferrer");+ return;+ }capture("v4_migration:delay_badge_clicked");openMigrationPanel({ id: project.id, name: project.name }, "delay_badge");};@@ -69,7 +86,7 @@ export function V4MigrationDelayBadge() {<V4MigrationBadgeContentonClick={handleClick}title="New data in ~15 min"- description={description}+ description={forceV3 ? "Learn more in the docs" : description}/>);}@@ -77,8 +94,8 @@ export function V4MigrationDelayBadge() {/** Shared gating for the eval "Action required" badges: v4 upgrade UI flag,* project context, and a loaded, non-zero deprecated-eval count. */function useEvalUpdateRequiredBadgeState() {- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();const { project, organization } = useQueryProject();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);const enabled = v4UpgradeUiEnabled && Boolean(project);const evalState = useProjectV4EvalData({projectId: project?.id,diff --git a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsxindex c88fdbbe86..36a10754d4 100644--- a/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationEntryPoints.clienttest.tsx@@ -61,6 +61,7 @@ const migrationStatus = (experiments: { status: "loaded", result: "not_required" },apis: { status: "loaded", count: 0 },exports: { status: "loaded", count: 0 },+ forceV3Experience: false,...overrides,});diff --git a/web/src/features/v4-migration/V4MigrationModal.tsx b/web/src/features/v4-migration/V4MigrationModal.tsxindex fbf8f32252..c96a756670 100644--- a/web/src/features/v4-migration/V4MigrationModal.tsx+++ b/web/src/features/v4-migration/V4MigrationModal.tsx@@ -17,7 +17,7 @@ import { api } from "@/src/utils/api";// use deprecated features (currently Evals) and opens on arrival.export function V4MigrationModal() {const { project } = useQueryProject();- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);const traceLevelEvalSummary = api.v4Transition.traceLevelEvalSummary.useQuery({ projectId: project?.id ?? "" },{diff --git a/web/src/features/v4-migration/V4MigrationNavItem.tsx b/web/src/features/v4-migration/V4MigrationNavItem.tsxindex 4c9cef27cd..7af397b721 100644--- a/web/src/features/v4-migration/V4MigrationNavItem.tsx+++ b/web/src/features/v4-migration/V4MigrationNavItem.tsx@@ -8,10 +8,10 @@ import { getProjectMigrationReadiness } from "@/src/features/v4-migration/migratimport { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";export function V4MigrationNavItem() {- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const { project, organization } = useQueryProject();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(project?.id);const openMigrationPanel = useOpenV4MigrationPanel();const { isMobile, setOpenMobile: setOpenMobileSidebar } = useSidebar();- const { project, organization } = useQueryProject();const capture = usePostHogClientCapture();const migrationData = useProjectV4MigrationData({projectId: project?.id,@@ -28,6 +28,7 @@ export function V4MigrationNavItem() {experiments: migrationData.experiments,apis: migrationData.apis,exports: migrationData.exports,+ forceV3Experience: migrationData.forceV3Experience,});if (readiness === "ready") {return null;diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsxindex 5e02443d15..67aa893c90 100644--- a/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.clienttest.tsx@@ -15,6 +15,10 @@ vi.mock("./useV4UpgradeUiEnabled", () => ({useV4UpgradeUiEnabled: () => flagState.enabled,}));+vi.mock("@/src/features/projects/hooks", () => ({+ useQueryProject: () => ({ project: null, organization: null }),+}));+vi.mock("@/src/features/posthog-analytics/usePostHogClientCapture", () => ({usePostHogClientCapture: () => captureMock,}));diff --git a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx b/web/src/features/v4-migration/V4MigrationPanelProvider.tsxindex 44397ce702..1ca0fc9a15 100644--- a/web/src/features/v4-migration/V4MigrationPanelProvider.tsx+++ b/web/src/features/v4-migration/V4MigrationPanelProvider.tsx@@ -6,6 +6,7 @@ import {} from "react";import { usePostHogClientCapture } from "@/src/features/posthog-analytics/usePostHogClientCapture";import { useV4UpgradeUiEnabled } from "@/src/features/v4-migration/useV4UpgradeUiEnabled";+import { useQueryProject } from "@/src/features/projects/hooks";export type V4MigrationTargetProject = { id: string; name: string };@@ -39,7 +40,8 @@ export function V4MigrationPanelProvider({children,defaultOpen = false,}: V4MigrationPanelProviderProps) {- const v4UpgradeUiEnabled = useV4UpgradeUiEnabled();+ const { project: routeProject } = useQueryProject();+ const v4UpgradeUiEnabled = useV4UpgradeUiEnabled(routeProject?.id);const capture = usePostHogClientCapture();const [requestedOpen, setRequestedOpen] = useState(defaultOpen);const [targetProject, setTargetProject] =diff --git a/web/src/features/v4-migration/V4MigrationProjectChip.tsx b/web/src/features/v4-migration/V4MigrationProjectChip.tsxindex b5bf4279a3..e049e1aeea 100644--- a/web/src/features/v4-migration/V4MigrationProjectChip.tsx+++ b/web/src/features/v4-migration/V4MigrationProjectChip.tsx@@ -5,6 +5,7 @@ import {type ProjectMigrationStatus,} from "@/src/features/v4-migration/migrationData";import { useOpenV4MigrationPanel } from "@/src/features/v4-migration/hooks/useOpenV4MigrationPanel";+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";export function V4MigrationProjectChip({project,@@ -17,6 +18,27 @@ export function V4MigrationProjectChip({const capture = usePostHogClientCapture();const readiness = status ? getProjectMigrationReadiness(status) : "checking";++ // Forced-v3 projects show no migration action β the upgrade is handled by+ // their integration partner. Point them at the FAQ instead.+ if (readiness === "partner-managed") {+ return (+ <a+ href={PARTNER_INTEGRATION_FAQ_URL}+ target="_blank"+ rel="noopener noreferrer"+ onClick={(event) => {+ // Card is wrapped in a full-bleed <Link>; keep the docs link isolated.+ event.stopPropagation();+ }}+ className="text-muted-foreground ring-border hover:bg-muted/50 relative inline-flex shrink-0 items-center gap-1.5 rounded-full px-2 py-0.5 text-xs whitespace-nowrap ring"+ title="Upgrade is handled by your integration partner. Click on badge to learn more."+ >+ Update to v4 managed by integration partner+ </a>+ );+ }+if (readiness === "ready") {return null;}diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsxindex 2d8160d539..95b3caca9b 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.clienttest.tsx@@ -90,6 +90,7 @@ vi.mock("@/src/features/v4-migration/hooks/useV4MigrationData", () => ({experiments: { status: "loaded", result: "not_required" },apis: { status: "loaded", count: 0 },exports: { status: "loaded", count: 0 },+ forceV3Experience: false,},],]),diff --git a/web/src/features/v4-migration/V4MigrationStatusPage.tsx b/web/src/features/v4-migration/V4MigrationStatusPage.tsxindex c58b15cc1d..fc2d833c4c 100644--- a/web/src/features/v4-migration/V4MigrationStatusPage.tsx+++ b/web/src/features/v4-migration/V4MigrationStatusPage.tsx@@ -34,6 +34,7 @@ import {type ProjectMigrationReadiness,type ProjectMigrationStatus,} from "@/src/features/v4-migration/migrationData";+import { PARTNER_INTEGRATION_FAQ_URL } from "@/src/features/v4-migration/partnerIntegrationDocs";const V4_DOCS_URL = "https://langfuse.com/docs/v4";const SDK_UPGRADE_URL =@@ -86,6 +87,23 @@ function MigrationActionCell({ state }: { state: MigrationActionState }) {}function StatusPill({ readiness }: { readiness: ProjectMigrationReadiness }) {+ // Forced-v3 projects are managed by their integration partner β link the pill+ // straight to the FAQ instead of showing a migration action state.+ if (readiness === "partner-managed") {+ return (+ <a+ href={PARTNER_INTEGRATION_FAQ_URL}+ target="_blank"+ rel="noopener noreferrer"+ onClick={(event) => event.stopPropagation()}+ className="bg-muted text-muted-foreground inline-flex w-fit shrink-0 items-center rounded-full px-2 py-0.5 text-xs font-bold whitespace-nowrap hover:underline"+ title="Upgrade is handled by your integration partner"+ >+ Integration partner+ </a>+ );+ }+const label =readiness === "ready"? "Migrated"@@ -175,8 +193,15 @@ function OrgStatusSection({openMigrationPanel({ id: row.id, name: row.name }, "status_page_row");};- const handleRowClick = (row: { id: string; name: string }) => {- openProjectMigration(row);+ const handleRowClick = (row: {+ id: string;+ name: string;+ status?: ProjectMigrationStatus;+ }) => {+ // Forced-v3 projects have no migration panel β just navigate to the project.+ if (!row.status?.forceV3Experience) {+ openProjectMigration(row);+ }router.push(`/project/${row.id}/traces`);};@@ -225,6 +250,7 @@ function OrgStatusSection({checking: 1,"action-needed": 2,ready: 3,+ "partner-managed": 4,}[getProjectMigrationReadiness(row.status)]: 0;case "sdk":@@ -352,7 +378,10 @@ function OrgStatusSection({title={row.name}onClick={(event) => {event.stopPropagation();- openProjectMigration(row);+ // Forced-v3 projects have no migration panel.+ if (!row.status?.forceV3Experience) {+ openProjectMigration(row);+ }}}>{row.name}diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.tsindex f401e31be8..cefd0dba44 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts@@ -142,6 +142,7 @@ describe("account v4 migration data", () => {},apis: { status: "loaded", count: 2 },exports: { status: "loaded", count: 1 },+ forceV3Experience: false,});expect(mocks.summaryByProject).toHaveBeenCalledWith({ orgId: "org-1" },@@ -156,4 +157,29 @@ describe("account v4 migration data", () => {expect.objectContaining({ enabled: true }),);});++ it("marks projects forced onto the v3 experience as partner-managed", () => {+ const [integrationResultSet] = mocks.queryResultSets as [+ [{ data: { projects: Record<string, unknown>[] } }],+ ...unknown[][],+ ];+ integrationResultSet[0].data.projects[0].forceV3Experience = true;++ const { result } = renderHook(() =>+ useAccountV4MigrationData({+ organizations: [+ {+ id: "org-1",+ name: "Organization",+ projects: [{ id: "project-1", name: "Project" }],+ },+ ],+ enabled: true,+ }),+ );++ expect(result.current.get("project-1")).toMatchObject({+ forceV3Experience: true,+ });+ });});diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.tsindex 9e37c73609..4df5b195ba 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.ts@@ -11,6 +11,7 @@ import {type ProjectMigrationStatus,} from "@/src/features/v4-migration/migrationData";import { getV4MigrationSdkState } from "@/src/features/v4-migration/sdkVersionStatus";+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";const QUERY_STALE_TIME_MS = 5 * 60 * 1000;@@ -85,7 +86,6 @@ export function useAccountV4MigrationData(params: {),),);-const statusByProjectId = new Map<string, ProjectMigrationStatus>();organizations.forEach((organization, organizationIndex) => {@@ -127,6 +127,13 @@ export function useAccountV4MigrationData(params: {?.legacyIntegrationCount ?? 0);}),+ // Forced-v3 projects still appear in the aggregation, marked as+ // partner-managed so surfaces can show "upgrade handled by your+ // integration partner" instead of a user-facing migration action.+ forceV3Experience:+ integrationQuery?.data?.projects.find(+ (row) => row.projectId === project.id,+ )?.forceV3Experience === true,});});});@@ -194,6 +201,7 @@ export function useProjectV4MigrationData(params: {const { projectId, orgId, enabled } = params;const queryEnabled = enabled && Boolean(projectId);const [detectionRange] = useState(createV4MigrationDetectionRange);+ const forceV3Experience = useForceV3Experience(projectId);const { sdkQuery, summary: sdkSummary } = useProjectV4SdkSummary({projectId,orgId,@@ -248,6 +256,7 @@ export function useProjectV4MigrationData(params: {integrationQuery,(data) => data.legacyIntegrationCount,),+ forceV3Experience,apiUsage,legacyIntegrations,};diff --git a/web/src/features/v4-migration/migrationData.clienttest.ts b/web/src/features/v4-migration/migrationData.clienttest.tsindex 684b0d3170..6531b594c0 100644--- a/web/src/features/v4-migration/migrationData.clienttest.ts+++ b/web/src/features/v4-migration/migrationData.clienttest.ts@@ -25,6 +25,7 @@ const migrationStatus = (experiments: loadedAction("not_required"),apis: loaded(0),exports: loaded(0),+ forceV3Experience: false,...overrides,});diff --git a/web/src/features/v4-migration/migrationData.ts b/web/src/features/v4-migration/migrationData.tsindex 342e9f6d06..8332d86b45 100644--- a/web/src/features/v4-migration/migrationData.ts+++ b/web/src/features/v4-migration/migrationData.ts@@ -85,17 +85,27 @@ export type ProjectMigrationStatus = {experiments: MigrationActionState;apis: MigrationCountState;exports: MigrationCountState;+ // Whether the project is forced onto the v3 experience (partner-managed+ // upgrade). Always set; `true` short-circuits readiness to "partner-managed".+ forceV3Experience: boolean;};export type ProjectMigrationReadiness =| "checking"| "unavailable"| "ready"- | "action-needed";+ | "action-needed"+ | "partner-managed";export const getProjectMigrationReadiness = (status: ProjectMigrationStatus,): ProjectMigrationReadiness => {+ // Forced-v3 projects don't migrate themselves β their integration partner+ // does. Surface that instead of any migration action state.+ if (status.forceV3Experience) {+ return "partner-managed";+ }+const counts = [status.evals, status.apis, status.exports];if (diff --git a/web/src/features/v4-migration/partnerIntegrationDocs.ts b/web/src/features/v4-migration/partnerIntegrationDocs.tsnew file mode 100644index 0000000000..70a26931f2--- /dev/null+++ b/web/src/features/v4-migration/partnerIntegrationDocs.ts@@ -0,0 +1,6 @@+// FAQ page for projects kept on the v3 experience because they are instrumented+// via an integration partner (e.g. VAPI) that has not upgraded to OTEL+// ingestion yet. The partner performs the upgrade for them; until then the v4+// migration prompts do not apply. Update the slug once the docs page ships.+export const PARTNER_INTEGRATION_FAQ_URL =+ "https://langfuse.com/faq/all/partner-integration-v4-upgrade";diff --git a/web/src/features/v4-migration/useForceV3Experience.ts b/web/src/features/v4-migration/useForceV3Experience.tsnew file mode 100644index 0000000000..6dc11d5e66--- /dev/null+++ b/web/src/features/v4-migration/useForceV3Experience.ts@@ -0,0 +1,21 @@+import { api } from "@/src/utils/api";++/**+ * Whether the given project is forced onto the v3 experience via+ * LANGFUSE_FORCE_V3_EXPERIENCE. The value is static per deployment, so it is+ * cached for the session. Returns false while loading or when no project id is+ * available (safe default: not forced).+ */+export function useForceV3Experience(projectId?: string): boolean {+ const forceV3 = api.v4Transition.forceV3Experience.useQuery(+ { projectId: projectId ?? "" },+ {+ // Callers that only need the value behind another gate (e.g. the v4+ // upgrade flag) can pass enabled:false to avoid firing the query for+ // users the answer can't affect.+ enabled: Boolean(projectId),+ staleTime: Infinity,+ },+ );+ return forceV3.data ?? false;+}diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.tsindex b72b7ff800..9919e0b0a0 100644--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.clienttest.ts@@ -3,15 +3,37 @@ import { useSession } from "next-auth/react";import { vi } from "vitest";import { useV4UpgradeUiEnabled } from "./useV4UpgradeUiEnabled";+import { useForceV3Experience } from "./useForceV3Experience";import { parseFlags } from "@/src/features/feature-flags/utils";vi.mock("next-auth/react", () => ({useSession: vi.fn(),}));+vi.mock("./useForceV3Experience", () => ({+ useForceV3Experience: vi.fn(),+}));+const mockUseSession = vi.mocked(useSession);+const mockUseForceV3Experience = vi.mocked(useForceV3Experience);++const mockSessionFlag = (v4UpgradeUi: boolean) => {+ mockUseSession.mockReturnValue({+ data: {+ user: {+ admin: false,+ featureFlags: { v4UpgradeUi },+ },+ environment: { enableExperimentalFeatures: false },+ },+ } as never);+};describe("useV4UpgradeUiEnabled", () => {+ beforeEach(() => {+ mockUseForceV3Experience.mockReturnValue(false);+ });+it("maps the database flag into the session flag shape", () => {const context = { email: undefined, v4BetaEnabled: false };expect(parseFlags(["v4UpgradeUi"], context).v4UpgradeUi).toBe(true);@@ -35,18 +57,28 @@ describe("useV4UpgradeUiEnabled", () => {});it("enables the UI only when the user flag is set", () => {- mockUseSession.mockReturnValue({- data: {- user: {- admin: false,- featureFlags: { v4UpgradeUi: true },- },- environment: { enableExperimentalFeatures: false },- },- } as never);+ mockSessionFlag(true);const { result } = renderHook(() => useV4UpgradeUiEnabled());expect(result.current).toBe(true);});++ it("suppresses the UI for projects forced onto the v3 experience", () => {+ mockSessionFlag(true);+ mockUseForceV3Experience.mockReturnValue(true);++ const { result } = renderHook(() => useV4UpgradeUiEnabled());++ expect(result.current).toBe(false);+ });++ it("stays disabled when the flag is off regardless of force-v3", () => {+ mockSessionFlag(false);+ mockUseForceV3Experience.mockReturnValue(false);++ const { result } = renderHook(() => useV4UpgradeUiEnabled());++ expect(result.current).toBe(false);+ });});diff --git a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts b/web/src/features/v4-migration/useV4UpgradeUiEnabled.tsindex 5235e7260e..db114a64e3 100644--- a/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts+++ b/web/src/features/v4-migration/useV4UpgradeUiEnabled.ts@@ -1,7 +1,25 @@import { useSession } from "next-auth/react";-export function useV4UpgradeUiEnabled(): boolean {+import { useForceV3Experience } from "@/src/features/v4-migration/useForceV3Experience";++/**+ * Raw `v4UpgradeUi` feature-preview flag, without the force-v3 suppression.+ */+export function useV4UpgradeUiFlag(): boolean {const { data: session } = useSession();return session?.user?.featureFlags.v4UpgradeUi === true;}++/**+ * Master gate for the v4 migration/upgrade UI. Every migration surface (nav+ * pill, upgrade badges, panel provider, banner, status page) checks this hook,+ * so returning false for a forced-v3 project hides all of them at once β and+ * automatically restores the sidebar "V4 Preview" toggle, which only renders+ * when the migration UI is off.+ */+export function useV4UpgradeUiEnabled(projectId?: string): boolean {+ const flag = useV4UpgradeUiFlag();+ const forceV3 = useForceV3Experience(projectId);+ return flag && !forceV3;+}diff --git a/web/src/features/v4/server/v4TransitionRouter.ts b/web/src/features/v4/server/v4TransitionRouter.tsindex d6f8ef9934..f56bdbedce 100644--- a/web/src/features/v4/server/v4TransitionRouter.ts+++ b/web/src/features/v4/server/v4TransitionRouter.ts@@ -13,6 +13,7 @@ import {classifyIngestionSdkVersion,convertDateToClickhouseDateTime,INTERNAL_INGESTION_SDK_NAMES,+ isForceV3ExperienceProject,logger,queryClickhouse,systemTableRef,@@ -277,6 +278,11 @@ const getLegacyIntegrations = ({});export const v4TransitionRouter = createTRPCRouter({+ // Whether this project is forced onto the v3 experience+ forceV3Experience: protectedProjectProcedure+ .input(z.object({ projectId: z.string() }))+ .query(({ input }) => isForceV3ExperienceProject(input.projectId)),+summary: protectedProjectProcedure.input(z.object({ projectId: z.string() })).query(async ({ input, ctx }) => {@@ -431,6 +437,7 @@ export const v4TransitionRouter = createTRPCRouter({legacyIntegrationCount:Object.values(legacyIntegrations).filter(Boolean).length,legacyIntegrations,+ forceV3Experience: isForceV3ExperienceProject(project.id),};}),};