@finos/legend-query-builder 4.19.4 → 4.19.6

package/src/__lib__/QueryBuilderTelemetryHelper.ts

@@ -38,8 +38,11 @@ type GraphFetchPanel_TelemtryData = {
 };
 
 export class QueryBuilderTelemetryHelper {
-  static logEvent_QueryRunLaunched(service: TelemetryService): void {
-    service.logEvent(QUERY_BUILDER_EVENT.RUN_QUERY__LAUNCH, {});
+  static logEvent_QueryRunLaunched(
+    service: TelemetryService,
+    data?: Record<string, unknown> | undefined,
+  ): void {
+    service.logEvent(QUERY_BUILDER_EVENT.RUN_QUERY__LAUNCH, data ?? {});
   }
 
   static logEvent_ExportQueryDataLaunched(service: TelemetryService): void {
@@ -67,6 +70,20 @@ export class QueryBuilderTelemetryHelper {
     service.logEvent(QUERY_BUILDER_EVENT.RUN_QUERY__SUCCESS, data);
   }
 
+  static logEvent_QueryRunFailed(
+    service: TelemetryService,
+    data: { errorMessage: string } & Record<string, unknown>,
+  ): void {
+    service.logEvent(QUERY_BUILDER_EVENT.RUN_QUERY__FAILURE, data);
+  }
+
+  static logEvent_QueryRunCancelled(
+    service: TelemetryService,
+    data?: Record<string, unknown> | undefined,
+  ): void {
+    service.logEvent(QUERY_BUILDER_EVENT.RUN_QUERY__CANCELLED, data ?? {});
+  }
+
   static logEvent_ExportQueryDataSucceeded(
     service: TelemetryService,
     data: QueryExecution_TelemetryData,

package/src/components/QueryAgentChat.tsx

@@ -0,0 +1,38 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import { observer } from 'mobx-react-lite';
+import { useApplicationStore } from '@finos/legend-application';
+import type { QueryBuilder_LegendApplicationPlugin_Extension } from '../stores/QueryBuilder_LegendApplicationPlugin_Extension.js';
+import type { QueryBuilderState } from '../stores/QueryBuilderState.js';
+
+export const QueryAgentChat = observer(
+  (props: { queryBuilderState: QueryBuilderState }) => {
+    const { queryBuilderState } = props;
+    const applicationStore = useApplicationStore();
+
+    const extraQueryAgentChatConfigurations = applicationStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap(
+        (plugin) =>
+          (
+            plugin as QueryBuilder_LegendApplicationPlugin_Extension
+          ).getExtraQueryAgentChatRenderers?.() ?? [],
+      );
+
+    return extraQueryAgentChatConfigurations[0]?.(queryBuilderState);
+  },
+);

package/src/components/QueryBuilder.tsx

@@ -79,6 +79,7 @@ import { QueryBuilderConstantExpressionPanel } from './QueryBuilderConstantExpre
 import { QUERY_BUILDER_SETTING_KEY } from '../__lib__/QueryBuilderSetting.js';
 import { QUERY_BUILDER_COMPONENT_ELEMENT_ID } from './QueryBuilderComponentElement.js';
 import { DataAccessOverview } from './data-access/DataAccessOverview.js';
+import { QueryAgentChat } from './QueryAgentChat.js';
 import { Fragment, useEffect, useRef } from 'react';
 import { RedoButton, UndoButton } from '@finos/legend-lego/application';
 import { FETCH_STRUCTURE_IMPLEMENTATION } from '../stores/fetch-structure/QueryBuilderFetchStructureImplementationState.js';
@@ -245,6 +246,9 @@ export const QueryBuilder = observer(
     const fetchStructureState = queryBuilderState.fetchStructureState;
     const isTDSState =
       fetchStructureState.implementation instanceof QueryBuilderTDSState;
+    const showQueryAgentChatPanel =
+      queryBuilderState.isAgentChatOpened &&
+      !queryBuilderState.config?.TEMPORARY__disableQueryBuilderAgentChat;
     const openLambdaEditor = (mode: QueryBuilderTextEditorMode): void =>
       queryBuilderState.textEditorState.openModal(mode);
     const openPure = (): void =>
@@ -1028,6 +1032,14 @@ export const QueryBuilder = observer(
                           {renderPostFetchStructure()}
                         </ResizablePanel>
                       )}
+                      {showQueryAgentChatPanel && <ResizablePanelSplitter />}
+                      {showQueryAgentChatPanel && (
+                        <ResizablePanel size={450}>
+                          <QueryAgentChat
+                            queryBuilderState={queryBuilderState}
+                          />
+                        </ResizablePanel>
+                      )}
                     </ResizablePanelGroup>
                   ) : (
                     <QueryBuilderUnsupportedQueryEditor
@@ -1114,9 +1126,9 @@ export const QueryBuilder = observer(
             />
           )}
         </div>
-        {queryBuilderState.workflowState.showStatusBar ? (
+        {queryBuilderState.workflowState.showStatusBar && (
           <QueryBuilderStatusBar queryBuilderState={queryBuilderState} />
-        ) : null}
+        )}
       </div>
     );
   },

package/src/components/QueryBuilderUnsupportedQueryEditor.tsx

@@ -28,6 +28,7 @@ import {
 } from '@finos/legend-art';
 import { QueryBuilderSidebar } from './QueryBuilderSideBar.js';
 import { QueryBuilderParametersPanel } from './QueryBuilderParametersPanel.js';
+import { QueryAgentChat } from './QueryAgentChat.js';
 
 const QueryBuilderUnsupportedQueryViewer = observer(
   (props: { queryBuilderState: QueryBuilderState }) => {
@@ -65,6 +66,9 @@ const QueryBuilderUnsupportedQueryViewer = observer(
 export const QueryBuilderUnsupportedQueryEditor = observer(
   (props: { queryBuilderState: QueryBuilderState }) => {
     const { queryBuilderState } = props;
+    const showQueryAgentChatPanel =
+      queryBuilderState.isAgentChatOpened &&
+      !queryBuilderState.config?.TEMPORARY__disableQueryBuilderAgentChat;
 
     return (
       <ResizablePanelGroup orientation="vertical">
@@ -81,6 +85,12 @@ export const QueryBuilderUnsupportedQueryEditor = observer(
             queryBuilderState={queryBuilderState}
           />
         </ResizablePanel>
+        {showQueryAgentChatPanel && <ResizablePanelSplitter />}
+        {showQueryAgentChatPanel && (
+          <ResizablePanel size={450}>
+            <QueryAgentChat queryBuilderState={queryBuilderState} />
+          </ResizablePanel>
+        )}
       </ResizablePanelGroup>
     );
   },

package/src/graph-manager/QueryBuilderConfig.ts

@@ -23,6 +23,11 @@ export class QueryBuilderConfig {
    */
   TEMPORARY__enableExportToCube = false;
 
+  /**
+   * This flag is to disable the Query Builder AI Agent chat panel toggle.
+   */
+  TEMPORARY__disableQueryBuilderAgentChat = false;
+
   /**
    * This flag is to enable AG-GRID enterprise mode
    */
@@ -50,6 +55,7 @@ export class QueryBuilderConfig {
 
   static readonly serialization = new SerializationFactory(
     createModelSchema(QueryBuilderConfig, {
+      TEMPORARY__disableQueryBuilderAgentChat: optional(primitive()),
       TEMPORARY__enableExportToCube: optional(primitive()),
       TEMPORARY__enableGridEnterpriseMode: optional(primitive()),
       legendMCPServiceURL: optional(primitive()),

package/src/index.ts

@@ -46,6 +46,7 @@ export {
   QueryBuilderExecutionContextState,
   QueryBuilderEmbeddedFromExecutionContextState,
 } from './stores/QueryBuilderExecutionContextState.js';
+export { QueryAgentChatState } from './stores/QueryAgentChatState.js';
 export {
   getTDSColumnDerivedProperyFromType,
   buildTDSSortTypeExpression,

package/src/stores/QueryAgentChatState.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) 2026-present, Goldman Sachs
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+export abstract class QueryAgentChatState {
+  /**
+   * When set, the current lambda in the builder was produced by the Legend
+   * AI agent chat (via "Load query into builder") and this is the `trace_id`
+   * the agent surfaced in its response. Downstream telemetry providers can
+   * pick this up to correlate save / update / run events to the agent
+   * conversation that produced them. In-memory only; not persisted.
+   *
+   * NOTE: subclasses are responsible for registering this field as
+   * `observable` (and `setAgentChatTraceId` as `action`) in their own
+   * `makeObservable` call — mobx does not support multiple `makeObservable`
+   * invocations across an inheritance chain on the same instance.
+   */
+  agentChatTraceId?: string | undefined;
+
+  setAgentChatTraceId(val: string | undefined): void {
+    this.agentChatTraceId = val;
+  }
+
+  abstract abort(): void;
+}

package/src/stores/QueryBuilderResultState.ts

@@ -504,6 +504,7 @@ export class QueryBuilderResultState {
 
       QueryBuilderTelemetryHelper.logEvent_QueryRunLaunched(
         this.queryBuilderState.applicationStore.telemetryService,
+        this.queryBuilderState.getExtraTelemetryMetadata(),
       );
 
       const stopWatch = new StopWatch();
@@ -547,6 +548,7 @@ export class QueryBuilderResultState {
           {},
           report,
           this.queryBuilderState.getStateInfo(),
+          this.queryBuilderState.getExtraTelemetryMetadata(),
         );
         QueryBuilderTelemetryHelper.logEvent_QueryRunSucceeded(
           this.queryBuilderState.applicationStore.telemetryService,
@@ -567,6 +569,14 @@ export class QueryBuilderResultState {
         if (error instanceof ExecutionError && error.executionTraceId) {
           this.setExecutionTraceId(error.executionTraceId);
         }
+        QueryBuilderTelemetryHelper.logEvent_QueryRunFailed(
+          this.queryBuilderState.applicationStore.telemetryService,
+          {
+            errorMessage:
+              error instanceof Error ? error.message : String(error),
+            ...this.queryBuilderState.getExtraTelemetryMetadata(),
+          },
+        );
       }
     } finally {
       this.setIsRunningQuery(false);
@@ -582,6 +592,10 @@ export class QueryBuilderResultState {
       yield this.queryBuilderState.graphManagerState.graphManager.cancelUserExecutions(
         true,
       );
+      QueryBuilderTelemetryHelper.logEvent_QueryRunCancelled(
+        this.queryBuilderState.applicationStore.telemetryService,
+        this.queryBuilderState.getExtraTelemetryMetadata(),
+      );
     } catch (error) {
       // Don't notify users about success or failure
       this.queryBuilderState.applicationStore.logService.error(

package/src/stores/QueryBuilderState.ts

@@ -115,8 +115,10 @@ import {
 } from './QueryBuilderExecutionContextState.js';
 import type { QueryBuilderConfig } from '../graph-manager/QueryBuilderConfig.js';
 import { QUERY_BUILDER_EVENT } from '../__lib__/QueryBuilderEvent.js';
+import { QUERY_BUILDER_SETTING_KEY } from '../__lib__/QueryBuilderSetting.js';
 import { QueryBuilderChangeHistoryState } from './QueryBuilderChangeHistoryState.js';
 import { type QueryBuilderWorkflowState } from './query-workflow/QueryBuilderWorkFlowState.js';
+import { type QueryAgentChatState } from './QueryAgentChatState.js';
 import type { QueryBuilder_LegendApplicationPlugin_Extension } from './QueryBuilder_LegendApplicationPlugin_Extension.js';
 import { createDataCubeViewerStateFromQueryBuilder } from './data-cube/QueryBuilderDataCubeHelper.js';
 import type { QueryBuilderDataCubeViewerState } from './data-cube/QueryBuilderDataCubeViewerState.js';
@@ -214,6 +216,7 @@ export abstract class QueryBuilderState implements CommandRegistrar {
   textEditorState: QueryBuilderTextEditorState;
   unsupportedQueryState: QueryBuilderUnsupportedQueryState;
   changeHistoryState: QueryBuilderChangeHistoryState;
+  isAgentChatOpened: boolean;
   showFunctionsExplorerPanel = false;
   showParametersPanel = false;
   isEditingWatermark = false;
@@ -230,6 +233,7 @@ export abstract class QueryBuilderState implements CommandRegistrar {
     QUERY_BUILDER_SUPPORTED_GET_ALL_FUNCTIONS.GET_ALL;
   executionContextState: QueryBuilderExecutionContextState;
   internalizeState?: QueryBuilderInternalizeState | undefined;
+  queryAgentChatState?: QueryAgentChatState | undefined;
 
   // NOTE: This property contains information about workflow used
   // to create this state. This should only be used to add additional
@@ -269,6 +273,8 @@ export abstract class QueryBuilderState implements CommandRegistrar {
       changeHistoryState: observable,
       executionContextState: observable,
       sourceElement: observable,
+      queryAgentChatState: observable,
+      isAgentChatOpened: observable,
       isLocalModeEnabled: observable,
       dataCubeViewerState: observable,
       getAllFunction: observable,
@@ -292,6 +298,7 @@ export abstract class QueryBuilderState implements CommandRegistrar {
       openDataCubeEngine: action,
       setIsCheckingEntitlments: action,
       setSourceElement: action,
+      setIsAgentChatOpened: action,
       setIsLocalModeEnabled: action,
       setGetAllFunction: action,
       setLambdaWriteMode: action,
@@ -304,6 +311,7 @@ export abstract class QueryBuilderState implements CommandRegistrar {
       changeMapping: action,
       changeRuntime: action,
       setExecutionContextState: action,
+      setQueryAgentChatState: action,
 
       rebuildWithQuery: action,
       compileQuery: flow,
@@ -335,6 +343,12 @@ export abstract class QueryBuilderState implements CommandRegistrar {
     this.config = config;
     this.workflowState = workflowState;
     this.sourceInfo = sourceInfo;
+    this.isAgentChatOpened =
+      (!this.config?.TEMPORARY__disableQueryBuilderAgentChat &&
+        this.applicationStore.settingService.getBooleanValue(
+          QUERY_BUILDER_SETTING_KEY.SHOW_QUERY_AGENT_CHAT_PANEL,
+        )) ??
+      false;
   }
 
   TEMPORARY_initializeExecContext(
@@ -457,6 +471,31 @@ export abstract class QueryBuilderState implements CommandRegistrar {
     }
   }
 
+  /**
+   * Aggregates extra telemetry metadata contributed by application plugins
+   * via `getExtraQueryBuilderTelemetryMetadataProviders`. Callers spread the
+   * result into their event payloads so telemetry helpers stay free of
+   * plugin-specific fields (e.g. agent chat trace ids).
+   */
+  getExtraTelemetryMetadata(): Record<string, unknown> {
+    const providers = this.applicationStore.pluginManager
+      .getApplicationPlugins()
+      .flatMap(
+        (plugin) =>
+          (
+            plugin as QueryBuilder_LegendApplicationPlugin_Extension
+          ).getExtraQueryBuilderTelemetryMetadataProviders?.() ?? [],
+      );
+    const metadata: Record<string, unknown> = {};
+    for (const provider of providers) {
+      const extra = provider(this);
+      if (extra) {
+        Object.assign(metadata, extra);
+      }
+    }
+    return metadata;
+  }
+
   /**
    * Gets information about the current queryBuilderState.
    * This information can be used as a part of analytics
@@ -482,6 +521,17 @@ export abstract class QueryBuilderState implements CommandRegistrar {
     return undefined;
   }
 
+  setIsAgentChatOpened(val: boolean): void {
+    if (val && this.config?.TEMPORARY__disableQueryBuilderAgentChat) {
+      return;
+    }
+    this.isAgentChatOpened = val;
+    this.applicationStore.settingService.persistValue(
+      QUERY_BUILDER_SETTING_KEY.SHOW_QUERY_AGENT_CHAT_PANEL,
+      val,
+    );
+  }
+
   setIsLocalModeEnabled(val: boolean): void {
     this.isLocalModeEnabled = val;
   }
@@ -496,6 +546,10 @@ export abstract class QueryBuilderState implements CommandRegistrar {
     this.internalizeState = val;
   }
 
+  setQueryAgentChatState(val: QueryAgentChatState | undefined): void {
+    this.queryAgentChatState = val;
+  }
+
   setShowFunctionsExplorerPanel(val: boolean): void {
     this.showFunctionsExplorerPanel = val;
   }

package/src/stores/QueryBuilder_LegendApplicationPlugin_Extension.ts

@@ -67,6 +67,10 @@ export type WarehouseEntitlementRender = {
   renderer: (dataAccessState: DataAccessState) => React.ReactNode;
 };
 
+export type QueryAgentChatRenderer = (
+  queryBuilderState: QueryBuilderState,
+) => React.ReactNode;
+
 export type TemplateQueryPanelContentRenderer = (
   queryBuilderState: QueryBuilderState,
 ) => React.ReactNode;
@@ -97,6 +101,16 @@ export type QueryBuilderPropagateExecutionContextChangeHelper = (
   isGraphBuildingNotRequired?: boolean,
 ) => (() => Promise<void>) | undefined;
 
+/**
+ * Contributes extra key/value pairs that should ride along with query-builder
+ * telemetry events (e.g. run query launch/success/failure, save query, ...).
+ * The returned bag is shallow-merged into the event payload by the caller;
+ * return `undefined` (or an empty object) to contribute nothing.
+ */
+export type QueryBuilderTelemetryMetadataProvider = (
+  queryBuilderState: QueryBuilderState,
+) => Record<string, unknown> | undefined;
+
 export interface QueryBuilder_LegendApplicationPlugin_Extension
   extends LegendApplicationPlugin {
   /**
@@ -131,6 +145,11 @@ export interface QueryBuilder_LegendApplicationPlugin_Extension
    */
   getExtraQueryUsageConfigurations?(): QueryExportUsageConfiguration[];
 
+  /**
+   * Get the list of query AI agent chat configurations.
+   */
+  getExtraQueryAgentChatRenderers?(): QueryAgentChatRenderer[];
+
   /**
    * Get the list of template query panel content render
    */
@@ -160,4 +179,13 @@ export interface QueryBuilder_LegendApplicationPlugin_Extension
    * Get the list of Query Builder Propagate Execution Context Change Helper
    */
   getExtraQueryBuilderPropagateExecutionContextChangeHelper?(): QueryBuilderPropagateExecutionContextChangeHelper[];
+
+  /**
+   * Get the list of providers that contribute extra key/value metadata to
+   * query-builder telemetry event payloads (agent-chat trace ids, custom
+   * environment tags, ...). Callers spread the aggregated metadata into
+   * their own event payloads via
+   * `QueryBuilderState.getExtraTelemetryMetadata()`.
+   */
+  getExtraQueryBuilderTelemetryMetadataProviders?(): QueryBuilderTelemetryMetadataProvider[];
 }

package/tsconfig.json

@@ -80,6 +80,7 @@
     "./src/graph-manager/protocol/pure/QueryBuilder_PureProtocolProcessorPlugin.ts",
     "./src/graph-manager/protocol/pure/v1/V1_QueryBuilder_PureGraphManagerExtension.ts",
     "./src/graph-manager/protocol/pure/v1/V1_QueryValueSpecificationBuilderHelper.ts",
+    "./src/stores/QueryAgentChatState.ts",
     "./src/stores/QueryBuilderChangeDetectionState.ts",
     "./src/stores/QueryBuilderChangeHistoryState.ts",
     "./src/stores/QueryBuilderCommand.ts",
@@ -230,6 +231,7 @@
     "./src/stores/workflows/accessor/AccessorQueryBuilderHelper.ts",
     "./src/stores/workflows/accessor/AccessorQueryBuilderState.ts",
     "./src/stores/workflows/dataProduct/DataProductQueryBuilderState.ts",
+    "./src/components/QueryAgentChat.tsx",
     "./src/components/QueryBuilder.tsx",
     "./src/components/QueryBuilderConstantExpressionPanel.tsx",
     "./src/components/QueryBuilderDiffPanel.tsx",