chrome-devtools-frontend 1.0.1711155 → 1.0.1715126

package/front_end/models/ai_assistance/agents/AiAgent.ts

@@ -23,6 +23,65 @@ import {
 type UrlString = Platform.DevToolsPath.UrlString;
 const MAX_SUGGESTION_LENGTH = 200;
 
+/**
+ * The types of event in the response stream that `AiConversation#run()`
+ * yields to the AI assistance panel. The same events, minus a few, are saved
+ * as the conversation history and replayed when a saved conversation opens.
+ *
+ * ## Order of events in one run
+ *
+ * ```
+ * USER_QUERY                    (AiConversation, first run of a query only)
+ * CONTEXT*                      (agent's handleContextDetails())
+ * repeated for each model request, up to MAX_STEPS:
+ *   QUERYING
+ *   one of:
+ *     ANSWER (complete: false)*, ANSWER (complete: true)   text-only reply; the run ends
+ *     [ANSWER (complete: true)], <tool call events>        function call, optionally with text
+ *     ERROR                                                the run ends
+ * ```
+ *
+ * An `ERROR` can also follow the tool call events, for example when the user
+ * aborts, the page navigates cross-origin, or the run reaches `MAX_STEPS`.
+ *
+ * ## Events for one tool call
+ *
+ * `AiAgent#callFunction()` yields these. All events for one call carry the
+ * same `callId`.
+ *
+ * ```
+ * TITLE?, THOUGHT?              from the tool's displayInfoFromArgs()
+ * if the tool needs approval:
+ *   ACTION {code}               code only, shown above the approval prompt;
+ *                               skipped if displayInfoFromArgs() has no action
+ *   SIDE_EFFECT                 the panel shows the prompt and calls confirm()
+ *   if denied: ACTION {code, output, canceled: true}, and the call ends
+ * ACTION {code, output, widgets, toolName}   result or error
+ * ```
+ *
+ * If the tool switches context instead of returning a result, there is no
+ * result `ACTION`. `AiAgent#run()` yields `CONTEXT_CHANGE` and returns, and
+ * `AiConversation` starts a new run with the agent for the new context.
+ *
+ * ## Saved history
+ *
+ * `AiConversation` saves every event except `CONTEXT_CHANGE` and partial
+ * `ANSWER`s. `AiConversation#serialize()` removes `confirm`, images and
+ * widgets, and redacts the `ACTION` output of tools annotated with
+ * `REDACT_FROM_HISTORY`. Saved data has no version field, so new fields must
+ * be optional.
+ *
+ * ## How the panel renders events
+ *
+ * `AiAssistancePanel#consumeResponseStream()` builds one chat message per
+ * `USER_QUERY` and one step per tool call:
+ * - `QUERYING` starts a new step with a spinner. The panel shows the step only
+ *   if it is the first part of the message. Otherwise, the step stays hidden
+ *   until a tool call fills it in.
+ * - `TITLE`, `THOUGHT`, `ACTION` and `SIDE_EFFECT` update the step for their
+ *   `callId`. Events saved before `callId` existed update the current step.
+ * - `ANSWER` adds the answer text. `ERROR` sets the message error.
+ */
 export const enum ResponseType {
   CONTEXT = 'context',
   TITLE = 'title',
@@ -68,6 +127,10 @@ export interface AnswerResponse {
   widgets?: AiWidget[];
 }
 
+/**
+ * No agent yields this event. The panel still handles it by attaching the
+ * suggestions to the last answer.
+ */
 export interface SuggestionsResponse {
   type: ResponseType.SUGGESTIONS;
   suggestions: [string, ...string[]];
@@ -83,32 +146,79 @@ export interface ContextDetail {
   text: string;
   codeLang?: string;
 }
+
+/**
+ * Describes the context sent with the user's query, such as the selected
+ * element. The agent's `handleContextDetails()` yields it before the first
+ * model request. The panel shows it as a completed "Analyzing data" step.
+ */
 export interface ContextResponse {
   type: ResponseType.CONTEXT;
   details: [ContextDetail, ...ContextDetail[]];
   widgets?: AiWidget[];
 }
 
-export interface TitleResponse {
+/**
+ * Identifies the tool call that an event belongs to. `AiAgent#callFunction()`
+ * generates one per call and sets it on every event for that call. Only the
+ * UI reads it; the agent never sends it to the model.
+ *
+ * Conversations saved before this field existed do not have it. The panel
+ * applies events without a `callId` to the current step.
+ */
+interface ToolCallEvent {
+  callId?: string;
+}
+
+/**
+ * The heading of a tool call's step, from `displayInfoFromArgs().title`.
+ */
+export interface TitleResponse extends ToolCallEvent {
   type: ResponseType.TITLE;
   title: string;
+  /**
+   * No agent sets this field.
+   */
   rpcId?: Host.AidaClient.RpcGlobalId;
 }
 
-export interface ThoughtResponse {
+/**
+ * Explanation text for a tool call's step, from
+ * `displayInfoFromArgs().thought`. The panel marks the step as completed when
+ * it receives a thought, even though the tool has not run yet.
+ */
+export interface ThoughtResponse extends ToolCallEvent {
   type: ResponseType.THOUGHT;
   thought: string;
+  /**
+   * No agent sets this field.
+   */
   rpcId?: Host.AidaClient.RpcGlobalId;
 }
 
-export interface SideEffectResponse {
+/**
+ * Asks the user to approve a tool call that has side effects. The agent waits
+ * until `confirm()` is called. If `displayInfoFromArgs()` returns an
+ * `action`, the agent yields it in a code-only `ACTION` just before this
+ * event.
+ */
+export interface SideEffectResponse extends ToolCallEvent {
   type: ResponseType.SIDE_EFFECT;
   description: string|null;
+  /**
+   * No agent sets this field. The code comes from the preceding `ACTION`.
+   */
   code?: string;
   confirm: (decision: PermissionDecision) => void;
   permissionPrompt?: PermissionPrompt;
   permissionTitle?: string;
 }
+
+/**
+ * Yielded when a tool selects a new context, for example a network request.
+ * `AiConversation` switches to the agent for that context and starts a new
+ * run. `AiConversation` does not save this event in the history.
+ */
 export interface ContextChangeResponse {
   type: ResponseType.CONTEXT_CHANGE;
   /**
@@ -123,22 +233,51 @@ export interface ContextChangeResponse {
 
 interface SerializedSideEffectResponse extends Omit<SideEffectResponse, 'confirm'> {}
 
-export interface ActionResponse {
+/**
+ * The code and result of a tool call. A call yields one or two:
+ * - Calls that need approval and have code first yield a code-only `ACTION`
+ *   (no `output`), so the panel can show the code above the approval prompt.
+ * - Every call that runs, fails or is denied ends with an `ACTION` that has
+ *   an `output`.
+ */
+export interface ActionResponse extends ToolCallEvent {
   type: ResponseType.ACTION;
+  /**
+   * The text shown in the step's code box, from
+   * `displayInfoFromArgs().action`. It is real code only for tools that run
+   * code, such as `executeJavaScript`. For other tools it is a readable form of
+   * the call.
+   */
   code?: string;
+  /**
+   * The tool's result, error message, or the denial message. Missing on the
+   * code-only `ACTION` that precedes an approval prompt.
+   */
   output?: string;
+  /**
+   * True if the user denied the call, so the tool did not run.
+   */
   canceled: boolean;
   widgets?: AiWidget[];
   /**
-   * The name of the executed tool. Only populated for AI v2.
+   * The name of the tool. Set on the result `ACTION` but not on the code-only
+   * or denied `ACTION`. `AiConversation#serialize()` uses it to redact the
+   * output of tools annotated with `REDACT_FROM_HISTORY`.
    */
   toolName?: string;
 }
 
+/**
+ * Yielded before each model request. The panel starts a new step for it.
+ */
 export interface QueryingResponse {
   type: ResponseType.QUERYING;
 }
 
+/**
+ * The user's query. Yielded by `AiConversation`, not by the agent, before
+ * the first run for the query. The panel starts a new chat message for it.
+ */
 export interface UserQuery {
   type: ResponseType.USER_QUERY;
   query: string;
@@ -476,7 +615,17 @@ export interface FunctionDeclaration<Args extends Record<string, unknown>, Retur
    */
   parameters: Host.AidaClient.FunctionObjectParam<keyof Args>;
   /**
-   * Provided a way to give information back to the UI.
+   * Returns the text the UI shows for a call to this function. The agent
+   * calls it before the handler runs.
+   *
+   * - `title`: the step heading, sent as `TITLE`.
+   * - `thought`: optional explanation shown in the step, sent as `THOUGHT`.
+   * - `action`: the text shown in the step's code box, sent as
+   *   `ACTION.code`. It is real code only for tools that run code, such as
+   *   `executeJavaScript`. For other tools it is a readable form of the call,
+   *   for example `getInsightDetails('NAVIGATION_0', 'LCPBreakdown')`, and is
+   *   never executed.
+   * - `suggestions`: `AiAgent` does not use this field.
    */
   displayInfoFromArgs?: (
       args: Args,
@@ -981,6 +1130,17 @@ export abstract class AiAgent<T> {
               response: {...result, widgets: undefined},
             },
           };
+          if (i === MAX_STEPS - 1) {
+            // Normally, the functionResponse is pushed at the start of the next
+            // iteration. Since no further iteration will run, push it here so the
+            // last functionCall is not left unpaired in history.
+            this.#history.push({
+              parts: [query],
+              role: Host.AidaClient.Role.ROLE_UNSPECIFIED,
+            });
+            yield this.#createErrorResponse(ErrorType.MAX_STEPS);
+            break;
+          }
           request = this.buildRequest(query, Host.AidaClient.Role.ROLE_UNSPECIFIED);
         } catch (err) {
           if (err instanceof CrossOriginError) {
@@ -995,11 +1155,6 @@ export abstract class AiAgent<T> {
         yield this.#createErrorResponse(ErrorType.UNKNOWN);
         break;
       }
-
-      if (i === MAX_STEPS - 1) {
-        yield this.#createErrorResponse(ErrorType.MAX_STEPS);
-        break;
-      }
     }
 
     if (isStructuredLogEnabled()) {
@@ -1042,6 +1197,7 @@ export abstract class AiAgent<T> {
       role: Host.AidaClient.Role.MODEL,
     });
 
+    const callId = crypto.randomUUID();
     let code;
     if (call.displayInfoFromArgs) {
       const {title, thought, action: callCode} = call.displayInfoFromArgs(args);
@@ -1049,6 +1205,7 @@ export abstract class AiAgent<T> {
       if (title) {
         yield {
           type: ResponseType.TITLE,
+          callId,
           title,
         };
       }
@@ -1056,6 +1213,7 @@ export abstract class AiAgent<T> {
       if (thought) {
         yield {
           type: ResponseType.THOUGHT,
+          callId,
           thought,
         };
       }
@@ -1078,6 +1236,7 @@ export abstract class AiAgent<T> {
       if (code) {
         yield {
           type: ResponseType.ACTION,
+          callId,
           code,
           canceled: false,
         };
@@ -1104,6 +1263,7 @@ export abstract class AiAgent<T> {
 
       yield {
         type: ResponseType.SIDE_EFFECT,
+        callId,
         confirm: sideEffectConfirmationPromiseWithResolvers.resolve,
         description: result.description,
         permissionPrompt: call.permissionPrompt,
@@ -1119,6 +1279,7 @@ export abstract class AiAgent<T> {
       if (decision === PermissionDecision.REJECT) {
         yield {
           type: ResponseType.ACTION,
+          callId,
           code,
           output: 'Error: User denied code execution with side effects.',
           canceled: true,
@@ -1152,6 +1313,7 @@ export abstract class AiAgent<T> {
     if ('result' in result) {
       yield {
         type: ResponseType.ACTION,
+        callId,
         code,
         output: typeof result.result === 'string' ? result.result : JSON.stringify(result.result),
         widgets: result.widgets,
@@ -1163,6 +1325,7 @@ export abstract class AiAgent<T> {
     if ('error' in result) {
       yield {
         type: ResponseType.ACTION,
+        callId,
         code,
         output: result.error,
         canceled: false,
@@ -1228,8 +1391,11 @@ export abstract class AiAgent<T> {
   }
 
   #createErrorResponse(error: ErrorType): ResponseData {
-    this.#removeLastRunParts();
-    this.clearCache();
+    // If we hit MAX_STEPS, we still want to keep the call history as this may be relevant for follow-up requests.
+    if (error !== ErrorType.MAX_STEPS) {
+      this.#removeLastRunParts();
+      this.clearCache();
+    }
     if (error !== ErrorType.ABORT) {
       Host.userMetrics.actionTaken(Host.UserMetrics.Action.AiAssistanceError);
     }

package/front_end/models/ai_assistance/agents/PerformanceAgent.snapshot.txt

@@ -150,10 +150,10 @@ Content:
           "",
           "## insight set id: NAVIGATION_1",
           "",
-          "- name: Google CDN, main thread time: 38 ms, network transfer size: 990 B",
+          "- name: Google CDN, main thread time: 43 ms, network transfer size: 990 B",
           "- name: web.dev, main thread time: 3 ms, network transfer size: 84.3 kB",
           "- name: Google Analytics, main thread time: 0.6 ms, network transfer size: 52.9 kB",
-          "- name: Google Fonts, main thread time: 0 ms, network transfer size: 42.2 kB",
+          "- name: Google Fonts, main thread time: 0.4 ms, network transfer size: 42.2 kB",
           "",
           "# Longest tasks",
           "",
@@ -256,6 +256,10 @@ Content:
           "    relevant trace bounds: {min: 658799775876µs, max: 658799791419µs}",
           "    example question: Show me the most impactful render-blocking requests that I should focus on",
           "    example question: How can I reduce the number of render-blocking requests?",
+          "  - insight name: ThirdParties",
+          "    description: 3rd party code can significantly impact load performance. [Reduce and defer loading of 3rd party code](https://developer.chrome.com/docs/performance/insights/third-parties) to prioritize your page’s content.",
+          "    relevant trace bounds: {min: 658799775876µs, max: 658799789804µs}",
+          "    example question: Which third parties are having the largest impact on my page performance?",
           "  - insight name: Cache",
           "    description: A long cache lifetime can speed up repeat visits to your page. [Learn more about caching](https://developer.chrome.com/docs/performance/insights/cache).",
           "    relevant trace bounds: {min: 658799777502µs, max: 658799791419µs}",
@@ -280,6 +284,7 @@ Content:
           "# 3rd party summary",
           "",
           "- name: GitHub, main thread time: 3 ms, network transfer size: 0 B",
+          "- name: Google Fonts, main thread time: 0.6 ms, network transfer size: 0 B",
           "",
           "# Longest tasks",
           "",

package/front_end/models/ai_assistance/agents/StylingAgent.snapshot.txt

@@ -359,10 +359,12 @@ Content:
   },
   {
     "type": "thought",
+    "callId": "00000000-0000-0000-0000-000000000001",
     "thought": "I am thinking."
   },
   {
     "type": "action",
+    "callId": "00000000-0000-0000-0000-000000000001",
     "code": "console.log('hello');",
     "output": "hello",
     "canceled": false,

package/front_end/models/ai_assistance/data_formatters/PerformanceInsightFormatter.snapshot.txt

@@ -796,43 +796,38 @@ This insight identified legacy JavaScript in your application's modules that may
 Polyfills and transforms enable older browsers to use new JavaScript features. However, many are not necessary for modern browsers. Consider modifying your JavaScript build process to not transpile Baseline features, unless you know you must support older browsers.
 
 ## Detailed analysis:
-Total legacy JavaScript: 8 files.
+Total legacy JavaScript: 7 files.
 
 Legacy JavaScript by file:
 
-- Script: https://s.yimg.com/aaq/benji/benji-2.2.99.js (eventKey: s-3387, ts: 157423742567) - Wasted bytes: 37204 bytes
-Matches:
-Line: 0, Column: 133, Name: Promise.allSettled
-
-- Script: https://s.yimg.com/aaq/c/25fa214.caas-news_web.min.js (eventKey: s-3412, ts: 157423743431) - Wasted bytes: 36084 bytes
+- Script: https://s.yimg.com/aaq/c/25fa214.caas-news_web.min.js (eventKey: s-3412, ts: 157423743431) - Wasted bytes: 37667 bytes
 Matches:
 Line: 0, Column: 13310, Name: Array.from
 Line: 0, Column: 14623, Name: Object.assign
 
-- Script: https://s.yimg.com/du/ay/wnsrvbjmeprtfrnfx.js (eventKey: s-6273, ts: 157423760794) - Wasted bytes: 12850 bytes
+- Script: https://s.yimg.com/aaq/benji/benji-2.2.99.js (eventKey: s-3387, ts: 157423742567) - Wasted bytes: 36554 bytes
+Matches:
+Line: 0, Column: 133, Name: Promise.allSettled
+
+- Script: https://s.yimg.com/du/ay/wnsrvbjmeprtfrnfx.js (eventKey: s-6273, ts: 157423760794) - Wasted bytes: 12851 bytes
 Matches:
 Line: 111, Column: 7829, Name: @babel/plugin-transform-spread
 Line: 111, Column: 1794, Name: Array.prototype.find
-Line: 111, Column: 2127, Name: Array.prototype.includes
 Line: 111, Column: 2748, Name: Object.values
 Line: 111, Column: 2473, Name: String.prototype.includes
 Line: 111, Column: 2627, Name: String.prototype.startsWith
 
-- Script: https://static.criteo.net/js/ld/publishertag.prebid.144.js (eventKey: s-257378, ts: 157426026656) - Wasted bytes: 10751 bytes
+- Script: https://static.criteo.net/js/ld/publishertag.prebid.144.js (eventKey: s-257378, ts: 157426026656) - Wasted bytes: 10904 bytes
 Matches:
 Line: 1, Column: 74871, Name: Array.isArray
 Line: 1, Column: 75344, Name: Array.prototype.filter
 Line: 1, Column: 75013, Name: Array.prototype.indexOf
 
-- Script: https://s.yimg.com/oa/consent.js (eventKey: s-3384, ts: 157423742450) - Wasted bytes: 8157 bytes
-Matches:
-Line: 1, Column: 132267, Name: Array.prototype.includes
-
-- Script: https://pm-widget.taboola.com/yahooweb-network/pmk-20220605.1.js (eventKey: s-52229, ts: 157424128231) - Wasted bytes: 7625 bytes
+- Script: https://pm-widget.taboola.com/yahooweb-network/pmk-20220605.1.js (eventKey: s-52229, ts: 157424128231) - Wasted bytes: 7655 bytes
 Matches:
 Line: 181, Column: 26, Name: Object.keys
 
-- Script: https://news.yahoo.com/ (eventKey: s-2116, ts: 157423489126) - Wasted bytes: 7141 bytes
+- Script: https://news.yahoo.com/ (eventKey: s-2116, ts: 157423489126) - Wasted bytes: 7235 bytes
 Matches:
 Line: 0, Column: 8382, Name: @babel/plugin-transform-classes
 Line: 0, Column: 107712, Name: Array.prototype.filter
@@ -840,7 +835,7 @@ Line: 0, Column: 107393, Name: Array.prototype.forEach
 Line: 0, Column: 108005, Name: Array.prototype.map
 Line: 0, Column: 108358, Name: String.prototype.includes
 
-- Script: https://cdn.taboola.com/libtrc/yahooweb-network/loader.js (eventKey: s-6352, ts: 157423761978) - Wasted bytes: 7061 bytes
+- Script: https://cdn.taboola.com/libtrc/yahooweb-network/loader.js (eventKey: s-6352, ts: 157423761978) - Wasted bytes: 7087 bytes
 Matches:
 Line: 0, Column: 390544, Name: Object.entries
 Line: 0, Column: 390688, Name: Object.values

package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.snapshot.txt

@@ -265,7 +265,7 @@ Here are all the insights that contain some related request from the given range
 - ThirdParties: cmp.js (consent.cmp.oath.com) (eventKey: s-3382, ts: 157423742399), gpt.js (securepubads.g.doubleclick.net) (eventKey: s-6244, ts: 157423760529), loader.js (cdn.taboola.com) (eventKey: s-6352, ts: 157423761978)
 - Cache: prebid-2.0.js (s.yimg.com) (eventKey: s-6279, ts: 157423760925), cmp.js (consent.cmp.oath.com) (eventKey: s-3382, ts: 157423742399), d1irmdsmbztlvx.js (s.yimg.com) (eventKey: s-6185, ts: 157423759200), consent.js (s.yimg.com) (eventKey: s-3384, ts: 157423742450), wnsrvbjmeprtfrnfx.js (s.yimg.com) (eventKey: s-6273, ts: 157423760794)
 - CharacterSet: news.yahoo.com/ (news.yahoo.com) (eventKey: s-2116, ts: 157423489126)
-- LegacyJavaScript: benji-2.2.99.js (s.yimg.com) (eventKey: s-3387, ts: 157423742567), 25fa214.caas-news_web.min.js (s.yimg.com) (eventKey: s-3412, ts: 157423743431), wnsrvbjmeprtfrnfx.js (s.yimg.com) (eventKey: s-6273, ts: 157423760794), consent.js (s.yimg.com) (eventKey: s-3384, ts: 157423742450), news.yahoo.com/ (news.yahoo.com) (eventKey: s-2116, ts: 157423489126)
+- LegacyJavaScript: 25fa214.caas-news_web.min.js (s.yimg.com) (eventKey: s-3412, ts: 157423743431), benji-2.2.99.js (s.yimg.com) (eventKey: s-3387, ts: 157423742567), wnsrvbjmeprtfrnfx.js (s.yimg.com) (eventKey: s-6273, ts: 157423760794), news.yahoo.com/ (news.yahoo.com) (eventKey: s-2116, ts: 157423489126), loader.js (cdn.taboola.com) (eventKey: s-6352, ts: 157423761978)
 === end content
 
 Title: PerformanceTraceFormatter formatTraceSummary web-dev.json.gz
@@ -380,7 +380,7 @@ Available insights:
     description: Polyfills and transforms enable older browsers to use new JavaScript features. However, many aren’t necessary for modern browsers. Consider modifying your JavaScript build process to not transpile [Baseline](https://web.dev/articles/baseline-and-polyfills) features, unless you know you must support older browsers. [Learn why most sites can deploy ES6+ code without transpiling](https://developer.chrome.com/docs/performance/insights/legacy-javascript).
     relevant trace bounds: {min: 157423489126µs, max: 157426132225µs}
     estimated metric savings: FCP 0 ms, LCP 0 ms
-    estimated wasted bytes: 126.9 kB
+    estimated wasted bytes: 120 kB
     example question: Is my site polyfilling modern JavaScript features?
     example question: How can I reduce the amount of legacy JavaScript on my page?
 === end content

package/front_end/models/ai_assistance/skills/lighthouse.md

@@ -1,6 +1,6 @@
 ---
 name: lighthouse
-description: Running Lighthouse reports and audits, full-page audits (performance, accessibility, best practices, Search Engine Optimization (SEO)), and inspecting Lighthouse scores.
+description: Running Lighthouse reports and audits when the user explicitly asks for Lighthouse, a Lighthouse score, or a multi-category audit (accessibility, best practices, Search Engine Optimization (SEO)). Not for general page performance measurement; use the performance skill for that.
 allowed-tools:
   - runLighthouse
   - getLighthouseAudits
@@ -31,4 +31,5 @@ Your role is to evaluate websites using Lighthouse audits across performance, ac
 # Considerations
 
 - Base all analysis on empirical Lighthouse audit data. Never fabricate audit scores or results.
+- For performance-only questions (e.g. loading speed, Core Web Vitals), do not run Lighthouse unless the user mentions Lighthouse or a Lighthouse score. Record a performance trace with the performance skill instead.
 - When summarizing a full Lighthouse run, highlight overall category scores first, then detail failing audits (score < 90).

package/front_end/models/ai_assistance/skills/performance.md

@@ -1,6 +1,6 @@
 ---
 name: performance
-description: Web performance analysis, Core Web Vitals (LCP, INP, CLS), trace inspection, and trace recording.
+description: Default skill for any page performance question. Measuring, testing, or debugging how fast a page loads or responds, Core Web Vitals (LCP, INP, CLS), recording performance traces, and trace analysis.
 allowed-tools:
   - recordPerformanceTrace
   - getTraceEventByKey
@@ -17,24 +17,28 @@ Your goal is to provide actionable advice about web page performance by analyzin
 
 # Investigation Workflow
 
-1. **Insight Inspection (`getInsightDetails`)**:
+1. **Trace Recording (`recordPerformanceTrace`)**:
+   - If no performance trace is in context and the user asks to measure, test, or debug page performance (e.g. loading speed, Core Web Vitals), call `recordPerformanceTrace` first.
+   - Prefer recording a trace over running Lighthouse for performance questions, unless the user explicitly asks for Lighthouse or a Lighthouse score.
+   - Use `recordPerformanceTrace` when the user requests a fresh live trace measurement.
+
+2. **Insight Inspection (`getInsightDetails`)**:
    - When asked about performance bottlenecks or Core Web Vitals (LCP, INP, CLS), never reply using only the initial summary.
    - Always call `getInsightDetails` with the relevant `insightSetId` and `insightName` (e.g. `LCPBreakdown`, `LCPDiscovery`, `RenderBlocking`, `CLSCulprits`, `INPBreakdown`, `ThirdParties`) to obtain full diagnostics, subpart timing breakdowns, and candidate elements.
    - For LCP investigations, inspect both `LCPBreakdown` and `LCPDiscovery` (TTFB, load delay, load duration, render delay).
 
-2. **Main Thread & Network Inspection (`getTraceMainThreadSummary` & `getTraceNetworkSummary`)**:
+3. **Main Thread & Network Inspection (`getTraceMainThreadSummary` & `getTraceNetworkSummary`)**:
    - Call `getTraceMainThreadSummary` with specific period labels (e.g. `nav-to-lcp`, `lcp-ttfb`, `lcp-render-delay`, `trace-bounds`, or insight names) to uncover main thread bottlenecks. Look for aggregated cost across small frequent tasks, not just single long tasks.
    - Use `getTraceNetworkSummary` with time bounds to inspect network requests during specific phases.
 
-3. **Call Tree, Event & Source Inspection**:
+4. **Call Tree, Event & Source Inspection**:
    - Use `getDetailedCallTree` to retrieve bottom-up execution trees for expensive main thread tasks.
    - Use `getTraceEventByKey` to inspect timing and payload data for individual events.
    - Use `getTraceFunctionCode` to inspect a specific function identified in the call tree, including line-by-line CPU profile execution costs.
    - Use `getTraceResourceContent` to inspect the full text of a script or resource captured within the trace by URL.
 
-4. **UI Selection & Trace Recording**:
+5. **UI Selection**:
    - Use `selectTraceEventByKey` to reveal and select an event in the Performance Flamechart if requested.
-   - Use `recordPerformanceTrace` when the user requests a fresh live trace measurement.
 
 # Considerations
 

package/front_end/models/ai_assistance/tools/RecordPerformanceTrace.ts

@@ -27,7 +27,7 @@ export class RecordPerformanceTraceTool implements
   readonly name: ToolName = ToolName.RECORD_PERFORMANCE_TRACE;
   readonly permissionPrompt: PermissionPrompt = PermissionPrompt.NEVER;
   readonly description: string =
-      'Reloads the page and records a new performance trace to measure, analyze, and debug page performance.';
+      'Reloads the page and records a new performance trace to measure, analyze, and debug page performance. Preferred tool for measuring page load performance and Core Web Vitals.';
 
   readonly parameters: Host.AidaClient.FunctionObjectParam<never> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,

package/front_end/models/ai_assistance/tools/ResolveDevtoolsNodePath.ts

@@ -3,6 +3,7 @@
 // found in the LICENSE file.
 
 import * as Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
 import * as SDK from '../../../core/sdk/sdk.js';
 
 import {
@@ -116,8 +117,19 @@ export class ResolveDevtoolsNodePathTool implements DataTool<ResolveDevtoolsNode
       return {error: 'Error: Node does not belong to the current origin.'};
     }
 
+    // Take a snapshot of the resolved node's DOM structure. This is required
+    // by the DOM_TREE UI widget to render the element's local tree in the AI response panel.
+    const snapshot = await node.takeSnapshot();
     return {
       result: {backendNodeId: node.backendNodeId()},
+      widgets: [{
+        name: 'DOM_TREE',
+        data: {
+          root: snapshot,
+          title: i18n.i18n.lockedString('Element details'),
+          accessibleRevealLabel: i18n.i18n.lockedString('Reveal element'),
+        },
+      }],
     };
   }
 }

package/front_end/models/ai_assistance/tools/RunLighthouse.ts

@@ -31,7 +31,7 @@ export class RunLighthouseTool implements
   readonly name: ToolName = ToolName.RUN_LIGHTHOUSE;
   readonly permissionPrompt: PermissionPrompt = PermissionPrompt.NEVER;
   readonly description: string =
-      'Runs Lighthouse audits on the active page. Supports "navigation" (for full initial page load audits), "snapshot" (for inspecting live in-page modifications without reload), and "timespan" (for interactions).';
+      'Runs Lighthouse audits on the active page. Supports "navigation" (for full initial page load audits), "snapshot" (for inspecting live in-page modifications without reload), and "timespan" (for interactions). Use only when the user asks for Lighthouse, a Lighthouse score, or a multi-category audit. For measuring page performance, record a performance trace instead.';
 
   readonly parameters: Host.AidaClient.FunctionObjectParam<keyof RunLighthouseArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,

package/front_end/models/ai_assistance/tools/Tool.ts

@@ -331,8 +331,17 @@ export interface BaseTool<ArgsType extends ToolArgs = ToolArgs> {
    */
   readonly parameters: Host.AidaClient.FunctionObjectParam<keyof ArgsType>;
   /**
-   * Converts the tool arguments into user-friendly display information.
-   * This is used by the UI to show what the agent is doing (e.g., in the history/steps log).
+   * Converts the tool arguments into the text the UI shows for a call to
+   * this tool. The agent calls it before the tool runs.
+   *
+   * - `title`: the step heading, sent as `TITLE`.
+   * - `thought`: optional explanation shown in the step, sent as `THOUGHT`.
+   * - `action`: the text shown in the step's code box, sent as
+   *   `ACTION.code`. It is real code only for tools that run code, such as
+   *   `executeJavaScript`. For other tools it is a readable form of the call,
+   *   for example `getInsightDetails('NAVIGATION_0', 'LCPBreakdown')`, and is
+   *   never executed.
+   * - `suggestions`: `AiAgent` does not use this field.
    */
   readonly displayInfoFromArgs?: (
       args: ArgsType,

package/front_end/models/bindings/DebuggerWorkspaceBinding.ts

@@ -158,6 +158,10 @@ export class DebuggerWorkspaceBinding implements SDK.TargetManager.SDKModelObser
       // Step out of an inlined function by stepping over its body.
       return {command: SDK.DebuggerModel.StepMode.STEP_OVER, ranges};
     }
+    if (mode === SDK.DebuggerModel.StepMode.STEP_OVER) {
+      // Enter outlined parts of the current function instead of stepping over the calls into them.
+      return {command: mode, ranges, enterRanges: SourceMapStepping.outlinedFunctionRanges(callFrames[0])};
+    }
     return {command: mode, ranges};
   }