AI: add Perf Insights formatter

This CL continues the work to lay the foundations of the Performance
Insights agent. Note that as of this CL the agent remains not usable and
is not expected to provide much value.

- Added `PerformanceInsightFormatter` class to format insight details,
  links, and descriptions.
- Updated `PerformanceInsightsAgent` to use the new formatter.
- Added `isLCPPhases` type guard to `LCPPhases.ts`. This allows us to
  take a generic insight and narrow the type down.

Bug: 394552594
Change-Id: I8b514bdb6d6ca404eca4f168a30254c0fba7b0e8
Reviewed-on: https://chromium-review.googlesource.com/c/devtools/devtools-frontend/+/6276133
Reviewed-by: Alex Rudenko <[email protected]>
Auto-Submit: Jack Franklin <[email protected]>
Commit-Queue: Jack Franklin <[email protected]>
Commit-Queue: Alex Rudenko <[email protected]>

Author: jackfranklin

config/gni/devtools_grd_files.gni

@@ -1202,6 +1202,7 @@ grd_files_debug_sources = [
   "front_end/panels/ai_assistance/components/userActionRow.css.js",
   "front_end/panels/ai_assistance/data_formatters/FileFormatter.js",
   "front_end/panels/ai_assistance/data_formatters/NetworkRequestFormatter.js",
+  "front_end/panels/ai_assistance/data_formatters/PerformanceInsightFormatter.js",
   "front_end/panels/ai_assistance/debug.js",
   "front_end/panels/animation/AnimationGroupPreviewUI.js",
   "front_end/panels/animation/AnimationScreenshotPopover.js",

front_end/models/trace/insights/LCPPhases.ts

@@ -85,6 +85,9 @@ interface LCPPhases {
   renderDelay: Types.Timing.Milli;
 }
 
+export function isLCPPhases(model: InsightModel<{}, {}>): model is LCPPhasesInsightModel {
+  return model.insightKey === 'LCPPhases';
+}
 export type LCPPhasesInsightModel = InsightModel<typeof UIStrings, {
   lcpMs?: Types.Timing.Milli,
   lcpTs?: Types.Timing.Milli,
@@ -93,9 +96,6 @@ export type LCPPhasesInsightModel = InsightModel<typeof UIStrings, {
   lcpRequest?: Types.Events.SyntheticNetworkRequest,
   phases?: LCPPhases,
 }>;
-export function isLCPPhases(model: InsightModel<{}, {}>): model is LCPPhasesInsightModel {
-  return model.title === UIStrings.title;
-}
 
 function anyValuesNaN(...values: number[]): boolean {
   return values.some(v => Number.isNaN(v));

front_end/panels/ai_assistance/BUILD.gn

@@ -35,6 +35,7 @@ devtools_module("ai_assistance") {
     "components/UserActionRow.ts",
     "data_formatters/FileFormatter.ts",
     "data_formatters/NetworkRequestFormatter.ts",
+    "data_formatters/PerformanceInsightFormatter.ts",
     "debug.ts",
   ]
 
@@ -100,12 +101,14 @@ ts_library("unittests") {
     "agents/NetworkAgent.test.ts",
     "agents/PatchAgent.test.ts",
     "agents/PerformanceAgent.test.ts",
+    "agents/PerformanceInsightsAgent.test.ts",
     "agents/StylingAgent.test.ts",
     "components/ChatView.test.ts",
     "components/MarkdownRendererWithCodeBlock.test.ts",
     "components/UserActionRow.test.ts",
     "data_formatters/FileFormatter.test.ts",
     "data_formatters/NetworkRequestFormatter.test.ts",
+    "data_formatters/PerformanceInsightFormatter.test.ts",
   ]
 
   deps = [

front_end/panels/ai_assistance/agents/PerformanceInsightsAgent.test.ts

@@ -0,0 +1,89 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import type * as Common from '../../../core/common/common.js';
+import type * as Host from '../../../core/host/host.js';
+import * as Trace from '../../../models/trace/trace.js';
+import {mockAidaClient} from '../../../testing/AiAssistanceHelpers.js';
+import * as TimelineUtils from '../../timeline/utils/utils.js';
+import {
+  InsightContext,
+  PerformanceInsightFormatter,
+  PerformanceInsightsAgent,
+  ResponseType,
+} from '../ai_assistance.js';
+
+const FAKE_LCP_MODEL = {
+  insightKey: 'LCPPhases',
+  strings: {},
+  title: 'LCP by phase' as Common.UIString.LocalizedString,
+  description: 'some description' as Common.UIString.LocalizedString,
+  category: Trace.Insights.Types.InsightCategory.ALL,
+  state: 'fail',
+} as const;
+const FAKE_PARSED_TRACE = {} as unknown as Trace.Handlers.Types.ParsedTrace;
+
+describe('PerformanceInsightsAgent', () => {
+  describe('handleContextDetails', () => {
+    it('outputs the right context for the initial query from the user', async () => {
+      const mockInsight = new TimelineUtils.InsightAIContext.ActiveInsight(FAKE_LCP_MODEL, FAKE_PARSED_TRACE);
+      const context = new InsightContext(mockInsight);
+      const agent = new PerformanceInsightsAgent({
+        aidaClient: mockAidaClient([[{
+          explanation: 'This is the answer',
+          metadata: {
+            rpcGlobalId: 123,
+          }
+        }]])
+      });
+
+      const responses = await Array.fromAsync(agent.run('test', {selected: context}));
+      assert.deepEqual(responses, [
+        {
+          type: ResponseType.USER_QUERY,
+          query: 'test',
+          imageInput: undefined,
+        },
+        {
+          type: ResponseType.CONTEXT,
+          title: 'LCP by phase',
+          details: [
+            // Note: these are placeholder values, see the TODO in
+            // PerformanceInsightsAgent.
+            {title: 'LCP by phase', text: 'LCP by phase'},
+          ],
+        },
+        {
+          type: ResponseType.QUERYING,
+        },
+        {
+          type: ResponseType.ANSWER,
+          text: 'This is the answer',
+          complete: true,
+          suggestions: undefined,
+          rpcId: 123,
+        },
+      ]);
+    });
+  });
+  describe('enhanceQuery', () => {
+    it('adds the context to the query from the user', async () => {
+      const agent = new PerformanceInsightsAgent({
+        aidaClient: {} as Host.AidaClient.AidaClient,
+      });
+
+      const mockInsight = new TimelineUtils.InsightAIContext.ActiveInsight(FAKE_LCP_MODEL, FAKE_PARSED_TRACE);
+      const context = new InsightContext(mockInsight);
+      const extraContext = new PerformanceInsightFormatter(mockInsight.insight).formatInsight();
+
+      const finalQuery = await agent.enhanceQuery('What is this?', context);
+      const expected = `${extraContext}
+
+# User request:
+What is this?`;
+
+      assert.strictEqual(finalQuery, expected);
+    });
+  });
+});

front_end/panels/ai_assistance/agents/PerformanceInsightsAgent.ts

@@ -6,15 +6,18 @@ import * as Host from '../../../core/host/host.js';
 import type * as Lit from '../../../ui/lit/lit.js';
 import type * as TimelineUtils from '../../timeline/utils/utils.js';
 import * as PanelUtils from '../../utils/utils.js';
+import {PerformanceInsightFormatter} from '../data_formatters/PerformanceInsightFormatter.js';
 
 import {
   type AgentOptions as BaseAgentOptions,
   AgentType,
   AiAgent,
+  type ContextDetail,
   type ContextResponse,
   ConversationContext,
   type RequestOptions,
   type ResponseData,
+  ResponseType,
 } from './AiAgent.js';
 
 /* clang-format off */
@@ -27,7 +30,7 @@ You will be told the following information about the Insight:
 - The 'Insight description' which helps you understand what the insight is for and what the user is hoping to understand.
 - 'Insight details' which will be additional context and information to help you understand what the insight is showing the user. Use this information to suggest opportunities to improve the performance.
 
-You have a number of functions to get information about the page and its performance. Use these functions to help you gather information to perform the user's query. For every query it is important to understand the network activity and also the main thread activity.
+You will also be provided with external resources. Use these to ensure you give correct, accurate and up to date answers.
 
 ## Step-by-step instructions
 
@@ -80,9 +83,17 @@ export class PerformanceInsightsAgent extends AiAgent<TimelineUtils.InsightAICon
   // eslint-disable-next-line no-unused-private-class-members
   #insight: ConversationContext<TimelineUtils.InsightAIContext.ActiveInsight>|undefined;
 
-  override handleContextDetails(_activeContext: ConversationContext<TimelineUtils.InsightAIContext.ActiveInsight>|null):
-      AsyncGenerator<ContextResponse, void, void> {
-    throw new Error('not implemented');
+  override async *
+      handleContextDetails(activeContext: ConversationContext<TimelineUtils.InsightAIContext.ActiveInsight>|null):
+          AsyncGenerator<ContextResponse, void, void> {
+    if (!activeContext) {
+      return;
+    }
+
+    const title = activeContext.getItem().title();
+    // TODO: Provide proper text with useful context details.
+    const titleDetail: ContextDetail = {title, text: title};
+    yield {type: ResponseType.CONTEXT, title, details: [titleDetail]};
   }
 
   override readonly type = AgentType.PERFORMANCE_INSIGHT;
@@ -105,6 +116,19 @@ export class PerformanceInsightsAgent extends AiAgent<TimelineUtils.InsightAICon
     // TODO: define the set of functions for the LLM.
   }
 
+  override async enhanceQuery(
+      query: string,
+      selectedInsight: ConversationContext<TimelineUtils.InsightAIContext.ActiveInsight>|null): Promise<string> {
+    if (!selectedInsight) {
+      return query;
+    }
+    const formatter = new PerformanceInsightFormatter(selectedInsight.getItem().insight);
+    const extraQuery = `${formatter.formatInsight()}\n\n# User request:\n`;
+
+    const finalQuery = `${extraQuery}${query}`;
+    return finalQuery;
+  }
+
   override async * run(initialQuery: string, options: {
     signal?: AbortSignal, selected: ConversationContext<TimelineUtils.InsightAIContext.ActiveInsight>|null,
   }): AsyncGenerator<ResponseData, void, void> {

front_end/panels/ai_assistance/ai_assistance.ts

@@ -20,3 +20,4 @@ export * from './EvaluateAction.js';
 export * from './ExtensionScope.js';
 export * from './data_formatters/FileFormatter.js';
 export * from './data_formatters/NetworkRequestFormatter.js';
+export * from './data_formatters/PerformanceInsightFormatter.js';

front_end/panels/ai_assistance/data_formatters/PerformanceInsightFormatter.test.ts

@@ -0,0 +1,43 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import {describeWithEnvironment} from '../../../testing/EnvironmentHelpers.js';
+import {getFirstOrError, getInsightOrError} from '../../../testing/InsightHelpers.js';
+import {TraceLoader} from '../../../testing/TraceLoader.js';
+import {PerformanceInsightFormatter} from '../ai_assistance.js';
+
+describe('PerformanceInsightFormatter', () => {
+  describeWithEnvironment('for LCP by Phase', () => {
+    it('serializes the correct details', async function() {
+      const {parsedTrace, insights} = await TraceLoader.traceEngine(this, 'web-dev-with-commit.json.gz');
+      assert.isOk(insights);
+      const firstNav = getFirstOrError(parsedTrace.Meta.navigationsByNavigationId.values());
+      const insight = getInsightOrError('LCPPhases', insights, firstNav);
+
+      const formatter = new PerformanceInsightFormatter(insight);
+      const output = formatter.formatInsight();
+
+      const expected = `## Insight title: LCP by phase
+
+## Insight Description:
+This insight is used to analyse the loading of the LCP resource and identify which of the 4 phases are contributing most to the delay in rendering the LCP element. For this insight it can be useful to get a list of all network requests that happened before the LCP time and look for slow requests. You can also look for main thread activity during the phases, in particular the load delay and render delay phases.
+
+## External resources:
+- https://web.dev/articles/lcp
+- https://web.dev/articles/optimize-lcp
+
+## Insight details:
+All time units given to you are in milliseconds.
+The actual LCP time is 129.21 ms;
+
+We can break this time down into the 4 phases that combine to make up the LCP time:
+
+- Time to first byte: 7.94 ms
+- Load delay: 33.16 ms
+- Load time: 14.70 ms
+- Render delay: 73.41 ms`;
+      assert.strictEqual(output, expected);
+    });
+  });
+});

front_end/panels/ai_assistance/data_formatters/PerformanceInsightFormatter.ts

@@ -0,0 +1,123 @@
+// Copyright 2025 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Trace from '../../../models/trace/trace.js';
+
+function formatMilli(x: number|undefined): string {
+  if (x === undefined) {
+    return '';
+  }
+  return i18n.TimeUtilities.preciseMillisToString(x, 2);
+}
+
+export class PerformanceInsightFormatter {
+  #insight: Trace.Insights.Types.InsightModel<{}, {}>;
+  constructor(insight: Trace.Insights.Types.InsightModel<{}, {}>) {
+    this.#insight = insight;
+  }
+
+  formatInsight(): string {
+    const {title} = this.#insight;
+    return `## Insight title: ${title}
+
+## Insight Description:
+${this.#description()}
+
+## External resources:
+${this.#links()}
+
+## Insight details:
+${this.#details()}`;
+  }
+
+  #details(): string {
+    if (Trace.Insights.Models.LCPPhases.isLCPPhases(this.#insight)) {
+      const {phases, lcpMs} = this.#insight;
+      if (!lcpMs) {
+        return '';
+      }
+
+      return `All time units given to you are in milliseconds.
+The actual LCP time is ${formatMilli(lcpMs)};
+
+We can break this time down into the 4 phases that combine to make up the LCP time:
+
+- Time to first byte: ${formatMilli(phases?.ttfb)}
+- Load delay: ${formatMilli(phases?.loadDelay)}
+- Load time: ${formatMilli(phases?.loadTime)}
+- Render delay: ${formatMilli(phases?.renderDelay)}`;
+    }
+    return '';
+  }
+
+  #links(): string {
+    switch (this.#insight.insightKey) {
+      case 'CLSCulprits':
+        return '';
+      case 'DocumentLatency':
+        return '';
+      case 'DOMSize':
+        return '';
+      case 'DuplicateJavaScript':
+        return '';
+      case 'FontDisplay':
+        return '';
+      case 'ForcedReflow':
+        return '';
+      case 'ImageDelivery':
+        return '';
+      case 'InteractionToNextPaint':
+        return '';
+      case 'LCPDiscovery':
+        return '';
+      case 'LCPPhases':
+        return `- https://web.dev/articles/lcp
+- https://web.dev/articles/optimize-lcp`;
+      case 'LongCriticalNetworkTree':
+        return '';
+      case 'RenderBlocking':
+        return '';
+      case 'SlowCSSSelector':
+        return '';
+      case 'ThirdParties':
+        return '';
+      case 'Viewport':
+        return '';
+    }
+  }
+  #description(): string {
+    switch (this.#insight.insightKey) {
+      case 'CLSCulprits':
+        return '';
+      case 'DocumentLatency':
+        return '';
+      case 'DOMSize':
+        return '';
+      case 'DuplicateJavaScript':
+        return '';
+      case 'FontDisplay':
+        return '';
+      case 'ForcedReflow':
+        return '';
+      case 'ImageDelivery':
+        return '';
+      case 'InteractionToNextPaint':
+        return '';
+      case 'LCPDiscovery':
+        return '';
+      case 'LCPPhases':
+        return 'This insight is used to analyse the loading of the LCP resource and identify which of the 4 phases are contributing most to the delay in rendering the LCP element. For this insight it can be useful to get a list of all network requests that happened before the LCP time and look for slow requests. You can also look for main thread activity during the phases, in particular the load delay and render delay phases.';
+      case 'LongCriticalNetworkTree':
+        return '';
+      case 'RenderBlocking':
+        return '';
+      case 'SlowCSSSelector':
+        return '';
+      case 'ThirdParties':
+        return '';
+      case 'Viewport':
+        return '';
+    }
+  }
+}

front_end/panels/timeline/utils/InsightAIContext.ts

@@ -21,6 +21,10 @@ export class ActiveInsight {
     this.#parsedTrace = parsedTrace;
   }
 
+  get insight(): Readonly<Trace.Insights.Types.InsightModel<{}, {}>> {
+    return this.#insight;
+  }
+
   title(): string {
     return this.#insight.title;
   }