chrome-devtools-mcp 0.0.2 → 0.2.0

package/build/node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AICallTree.js

@@ -0,0 +1,366 @@
+// Copyright 2024 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Root from '../../../core/root/root.js';
+import * as Trace from '../../../models/trace/trace.js';
+import * as SourceMapsResolver from '../../../models/trace_source_maps_resolver/trace_source_maps_resolver.js';
+/** Iterates from a node down through its descendents. If the callback returns true, the loop stops. */
+function depthFirstWalk(nodes, callback) {
+    for (const node of nodes) {
+        if (callback?.(node)) {
+            break;
+        }
+        depthFirstWalk(node.children().values(), callback); // Go deeper.
+    }
+}
+export class AICallTree {
+    selectedNode;
+    rootNode;
+    parsedTrace;
+    constructor(selectedNode, rootNode, parsedTrace) {
+        this.selectedNode = selectedNode;
+        this.rootNode = rootNode;
+        this.parsedTrace = parsedTrace;
+    }
+    static findEventsForThread({ thread, parsedTrace, bounds }) {
+        const threadEvents = parsedTrace.data.Renderer.processes.get(thread.pid)?.threads.get(thread.tid)?.entries;
+        if (!threadEvents) {
+            return null;
+        }
+        return threadEvents.filter(e => Trace.Helpers.Timing.eventIsInBounds(e, bounds));
+    }
+    static findMainThreadTasks({ thread, parsedTrace, bounds }) {
+        const threadEvents = parsedTrace.data.Renderer.processes.get(thread.pid)?.threads.get(thread.tid)?.entries;
+        if (!threadEvents) {
+            return null;
+        }
+        return threadEvents.filter(Trace.Types.Events.isRunTask)
+            .filter(e => Trace.Helpers.Timing.eventIsInBounds(e, bounds));
+    }
+    /**
+     * Builds a call tree representing all calls within the given timeframe for
+     * the provided thread.
+     * Events that are less than 0.05% of the range duration are removed.
+     */
+    static fromTimeOnThread({ thread, parsedTrace, bounds }) {
+        const overlappingEvents = this.findEventsForThread({ thread, parsedTrace, bounds });
+        if (!overlappingEvents) {
+            return null;
+        }
+        const visibleEventsFilter = new Trace.Extras.TraceFilter.VisibleEventsFilter(Trace.Styles.visibleTypes());
+        // By default, we remove events whose duration is less than 0.5% of the total
+        // range. So if the range is 10s, an event must be 0.05s+ to be included.
+        // This does risk eliminating useful data when we pass it to the LLM, but
+        // we are trying to balance context window sizes and not using it up too
+        // eagerly. We will experiment with this filter and likely make it smarter
+        // or tweak it based on range size rather than using a blanket value. Or we
+        // could consider limiting the depth when we serialize. Or some
+        // combination!
+        const minDuration = Trace.Types.Timing.Micro(bounds.range * 0.005);
+        const minDurationFilter = new MinDurationFilter(minDuration);
+        const compileCodeFilter = new ExcludeCompileCodeFilter();
+        // Build a tree bounded by the selected event's timestamps, and our other filters applied
+        const rootNode = new Trace.Extras.TraceTree.TopDownRootNode(overlappingEvents, {
+            filters: [minDurationFilter, compileCodeFilter, visibleEventsFilter],
+            startTime: Trace.Helpers.Timing.microToMilli(bounds.min),
+            endTime: Trace.Helpers.Timing.microToMilli(bounds.max),
+            doNotAggregate: true,
+            includeInstantEvents: true,
+        });
+        const instance = new AICallTree(null /* no selected node*/, rootNode, parsedTrace);
+        return instance;
+    }
+    /**
+     * Attempts to build an AICallTree from a given selected event. It also
+     * validates that this event is one that we support being used with the AI
+     * Assistance panel, which [as of January 2025] means:
+     * 1. It is on the main thread.
+     * 2. It exists in either the Renderer or Sample handler's entryToNode map.
+     * This filters out other events we make such as SyntheticLayoutShifts which are not valid
+     * If the event is not valid, or there is an unexpected error building the tree, `null` is returned.
+     */
+    static fromEvent(selectedEvent, parsedTrace) {
+        // Special case: performance.mark events are shown on the main thread
+        // technically, but because they are instant events they are shown with a
+        // tiny duration. Because they are instant, they also don't have any
+        // children or a call tree, and so if the user has selected a performance
+        // mark in the timings track, we do not want to attempt to build a call
+        // tree. Context: crbug.com/418223469
+        // Note that we do not have to repeat this check for performance.measure
+        // events because those are synthetic, and therefore the check
+        // further down about if this event is known to the RenderHandler
+        // deals with this.
+        if (Trace.Types.Events.isPerformanceMark(selectedEvent)) {
+            return null;
+        }
+        // First: check that the selected event is on the thread we have identified as the main thread.
+        const threads = Trace.Handlers.Threads.threadsInTrace(parsedTrace.data);
+        const thread = threads.find(t => t.pid === selectedEvent.pid && t.tid === selectedEvent.tid);
+        if (!thread) {
+            return null;
+        }
+        // We allow two thread types to deal with the NodeJS use case.
+        // MAIN_THREAD is used when a trace has been generated through Chrome
+        //   tracing on a website (and we have a renderer)
+        // CPU_PROFILE is used only when we have received a CPUProfile - in this
+        //   case all the threads are CPU_PROFILE so we allow those. If we only allow
+        //   MAIN_THREAD then we wouldn't ever allow NodeJS users to use the AI
+        //   integration.
+        if (thread.type !== "MAIN_THREAD" /* Trace.Handlers.Threads.ThreadType.MAIN_THREAD */ &&
+            thread.type !== "CPU_PROFILE" /* Trace.Handlers.Threads.ThreadType.CPU_PROFILE */) {
+            return null;
+        }
+        // Ensure that the event is known to either the Renderer or Samples
+        // handler. This helps exclude synthetic events we build up for other
+        // information such as Layout Shift clusters.
+        // We check Renderer + Samples to ensure we support CPU Profiles (which do
+        // not populate the Renderer Handler)
+        const data = parsedTrace.data;
+        if (!data.Renderer.entryToNode.has(selectedEvent) && !data.Samples.entryToNode.has(selectedEvent)) {
+            return null;
+        }
+        const allEventsEnabled = Root.Runtime.experiments.isEnabled('timeline-show-all-events');
+        const { startTime, endTime } = Trace.Helpers.Timing.eventTimingsMilliSeconds(selectedEvent);
+        const selectedEventBounds = Trace.Helpers.Timing.traceWindowFromMicroSeconds(Trace.Helpers.Timing.milliToMicro(startTime), Trace.Helpers.Timing.milliToMicro(endTime));
+        let threadEvents = data.Renderer.processes.get(selectedEvent.pid)?.threads.get(selectedEvent.tid)?.entries;
+        if (!threadEvents) {
+            // None from the renderer: try the samples handler, this might be a CPU trace.
+            threadEvents = data.Samples.profilesInProcess.get(selectedEvent.pid)?.get(selectedEvent.tid)?.profileCalls;
+        }
+        if (!threadEvents) {
+            console.warn(`AICallTree: could not find thread for selected entry: ${selectedEvent}`);
+            return null;
+        }
+        const overlappingEvents = threadEvents.filter(e => Trace.Helpers.Timing.eventIsInBounds(e, selectedEventBounds));
+        const filters = [new SelectedEventDurationFilter(selectedEvent), new ExcludeCompileCodeFilter(selectedEvent)];
+        // If the "Show all events" experiment is on, we don't filter out any
+        // events here, otherwise the generated call tree will not match what the
+        // user is seeing.
+        if (!allEventsEnabled) {
+            filters.push(new Trace.Extras.TraceFilter.VisibleEventsFilter(Trace.Styles.visibleTypes()));
+        }
+        // Build a tree bounded by the selected event's timestamps, and our other filters applied
+        const rootNode = new Trace.Extras.TraceTree.TopDownRootNode(overlappingEvents, {
+            filters,
+            startTime,
+            endTime,
+            includeInstantEvents: true,
+        });
+        // Walk the tree to find selectedNode
+        let selectedNode = null;
+        depthFirstWalk([rootNode].values(), node => {
+            if (node.event === selectedEvent) {
+                selectedNode = node;
+                return true;
+            }
+            return;
+        });
+        if (selectedNode === null) {
+            console.warn(`Selected event ${selectedEvent} not found within its own tree.`);
+            return null;
+        }
+        const instance = new AICallTree(selectedNode, rootNode, parsedTrace);
+        // instance.logDebug();
+        return instance;
+    }
+    /**
+     * Iterates through nodes level by level using a Breadth-First Search (BFS) algorithm.
+     * BFS is important here because the serialization process assumes that direct child nodes
+     * will have consecutive IDs (horizontally across each depth).
+     *
+     * Example tree with IDs:
+     *
+     *             1
+     *            / \
+     *           2   3
+     *        / / /   \
+     *      4  5 6     7
+     *
+     * Here, node with an ID 2 has consecutive children in the 4-6 range.
+     *
+     * To optimize for space, the provided `callback` function is called to serialize
+     * each node as it's visited during the BFS traversal.
+     *
+     * When serializing a node, the callback receives:
+     * 1. The current node being visited.
+     * 2. The ID assigned to this current node (a simple incrementing index based on visit order).
+     * 3. The predicted starting ID for the children of this current node.
+     *
+     * A serialized node needs to know the ID range of its children. However,
+     * child node IDs are only assigned when those children are themselves visited.
+     * To handle this, we predict the starting ID for a node's children. This prediction
+     * is based on a running count of all nodes that have ever been added to the BFS queue.
+     * Since IDs are assigned consecutively as nodes are processed from the queue, and a
+     * node's children are added to the end of the queue when the parent is visited,
+     * their eventual IDs will follow this running count.
+     */
+    breadthFirstWalk(nodes, serializeNodeCallback) {
+        const queue = Array.from(nodes);
+        let nodeIndex = 1;
+        // To predict the visited children indexes
+        let nodesAddedToQueueCount = queue.length;
+        let currentNode = queue.shift();
+        while (currentNode) {
+            if (currentNode.children().size > 0) {
+                serializeNodeCallback(currentNode, nodeIndex, nodesAddedToQueueCount + 1);
+            }
+            else {
+                serializeNodeCallback(currentNode, nodeIndex);
+            }
+            queue.push(...Array.from(currentNode.children().values()));
+            nodesAddedToQueueCount += currentNode.children().size;
+            currentNode = queue.shift();
+            nodeIndex++;
+        }
+    }
+    serialize(headerLevel = 1) {
+        const header = '#'.repeat(headerLevel);
+        // Keep a map of URLs. We'll output a LUT to keep size down.
+        const allUrls = [];
+        let nodesStr = '';
+        this.breadthFirstWalk(this.rootNode.children().values(), (node, nodeId, childStartingNode) => {
+            nodesStr +=
+                '\n' + this.stringifyNode(node, nodeId, this.parsedTrace, this.selectedNode, allUrls, childStartingNode);
+        });
+        let output = '';
+        if (allUrls.length) {
+            // Output lookup table of URLs within this tree
+            output += `\n${header} All URLs:\n\n` + allUrls.map((url, index) => `  * ${index}: ${url}`).join('\n');
+        }
+        output += `\n\n${header} Call tree:\n${nodesStr}`;
+        return output;
+    }
+    /*
+    * Each node is serialized into a single line to minimize token usage in the context window.
+    * The format is a semicolon-separated string with the following fields:
+    * Format: `id;name;duration;selfTime;urlIndex;childRange;[S]
+    *
+    *   1. `id`: A unique numerical identifier for the node assigned by BFS.
+    *   2. `name`: The name of the event represented by the node.
+    *   3. `duration`: The total duration of the event in milliseconds, rounded to one decimal place.
+    *   4. `selfTime`: The self time of the event in milliseconds, rounded to one decimal place.
+    *   5. `urlIndex`: An index referencing a URL in the `allUrls` array. If no URL is present, this is an empty string.
+    *   6. `childRange`: A string indicating the range of IDs for the node's children. Children should always have consecutive IDs.
+    *                    If there is only one child, it's a single ID.
+    *   7. `[S]`: An optional marker indicating that this node is the selected node.
+    *
+    * Example:
+    *   `1;Parse HTML;2.5;0.3;0;2-5;S`
+    *   This represents:
+    *     - Node ID 1
+    *     - Name "Parse HTML"
+    *     - Total duration of 2.5ms
+    *     - Self time of 0.3ms
+    *     - URL index 0 (meaning the URL is the first one in the `allUrls` array)
+    *     - Child range of IDs 2 to 5
+    *     - This node is the selected node (S marker)
+    */
+    stringifyNode(node, nodeId, parsedTrace, selectedNode, allUrls, childStartingNodeIndex) {
+        const event = node.event;
+        if (!event) {
+            throw new Error('Event required');
+        }
+        // 1. ID
+        const idStr = String(nodeId);
+        // 2. Name
+        const name = Trace.Name.forEntry(event, parsedTrace);
+        // Round milliseconds to one decimal place, return empty string if zero/undefined
+        const roundToTenths = (num) => {
+            if (!num) {
+                return '';
+            }
+            return String(Math.round(num * 10) / 10);
+        };
+        // 3. Duration
+        const durationStr = roundToTenths(node.totalTime);
+        // 4. Self Time
+        const selfTimeStr = roundToTenths(node.selfTime);
+        // 5. URL Index
+        const url = SourceMapsResolver.SourceMapsResolver.resolvedURLForEntry(parsedTrace, event);
+        let urlIndexStr = '';
+        if (url) {
+            const existingIndex = allUrls.indexOf(url);
+            if (existingIndex === -1) {
+                urlIndexStr = String(allUrls.push(url) - 1);
+            }
+            else {
+                urlIndexStr = String(existingIndex);
+            }
+        }
+        // 6. Child Range
+        const children = Array.from(node.children().values());
+        let childRangeStr = '';
+        if (childStartingNodeIndex) {
+            childRangeStr = (children.length === 1) ? String(childStartingNodeIndex) :
+                `${childStartingNodeIndex}-${childStartingNodeIndex + children.length}`;
+        }
+        // 7. Selected Marker
+        const selectedMarker = selectedNode?.event === node.event ? 'S' : '';
+        // Combine fields
+        let line = idStr;
+        line += ';' + name;
+        line += ';' + durationStr;
+        line += ';' + selfTimeStr;
+        line += ';' + urlIndexStr;
+        line += ';' + childRangeStr;
+        if (selectedMarker) {
+            line += ';' + selectedMarker;
+        }
+        return line;
+    }
+    // Only used for debugging.
+    logDebug() {
+        const str = this.serialize();
+        // eslint-disable-next-line no-console
+        console.log('🎆', str);
+        if (str.length > 45_000) {
+            // Manual testing shows 45k fits. 50k doesn't.
+            // Max is 32k _tokens_, but tokens to bytes is wishywashy, so... hard to know for sure.
+            console.warn('Output will likely not fit in the context window. Expect an AIDA error.');
+        }
+    }
+}
+/**
+ * These events are very noisy and take up room in the context window for no real benefit.
+ */
+export class ExcludeCompileCodeFilter extends Trace.Extras.TraceFilter.TraceFilter {
+    #selectedEvent = null;
+    constructor(selectedEvent) {
+        super();
+        this.#selectedEvent = selectedEvent ?? null;
+    }
+    accept(event) {
+        if (this.#selectedEvent && event === this.#selectedEvent) {
+            // If the user selects this event, we should accept it, else the
+            // behaviour is confusing when the selected event is not used.
+            return true;
+        }
+        return event.name !== "V8.CompileCode" /* Trace.Types.Events.Name.COMPILE_CODE */;
+    }
+}
+export class SelectedEventDurationFilter extends Trace.Extras.TraceFilter.TraceFilter {
+    #minDuration;
+    #selectedEvent;
+    constructor(selectedEvent) {
+        super();
+        // The larger the selected event is, the less small ones matter. We'll exclude items under ½% of the selected event's size
+        this.#minDuration = Trace.Types.Timing.Micro((selectedEvent.dur ?? 1) * 0.005);
+        this.#selectedEvent = selectedEvent;
+    }
+    accept(event) {
+        if (event === this.#selectedEvent) {
+            return true;
+        }
+        return event.dur ? event.dur >= this.#minDuration : false;
+    }
+}
+export class MinDurationFilter extends Trace.Extras.TraceFilter.TraceFilter {
+    #minDuration;
+    constructor(minDuration) {
+        super();
+        this.#minDuration = minDuration;
+    }
+    accept(event) {
+        return event.dur ? event.dur >= this.#minDuration : false;
+    }
+}

package/build/node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js

@@ -0,0 +1,64 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Trace from '../../../models/trace/trace.js';
+function getFirstInsightSet(insights) {
+    // Currently only support a single insight set. Pick the first one with a navigation.
+    // TODO(cjamcl): we should just give the agent the entire insight set, and give
+    // summary detail about all of them + the ability to query each.
+    return [...insights.values()].filter(insightSet => insightSet.navigation).at(0) ?? null;
+}
+export class AgentFocus {
+    static full(parsedTrace) {
+        if (!parsedTrace.insights) {
+            throw new Error('missing insights');
+        }
+        const insightSet = getFirstInsightSet(parsedTrace.insights);
+        return new AgentFocus({
+            type: 'full',
+            parsedTrace,
+            insightSet,
+        });
+    }
+    static fromInsight(parsedTrace, insight) {
+        if (!parsedTrace.insights) {
+            throw new Error('missing insights');
+        }
+        const insightSet = getFirstInsightSet(parsedTrace.insights);
+        return new AgentFocus({
+            type: 'insight',
+            parsedTrace,
+            insightSet,
+            insight,
+        });
+    }
+    static fromCallTree(callTree) {
+        const insights = callTree.parsedTrace.insights;
+        // Select the insight set containing the call tree.
+        // If for some reason that fails, fallback to the first one.
+        let insightSet = null;
+        if (insights) {
+            const callTreeTimeRange = Trace.Helpers.Timing.traceWindowFromEvent(callTree.rootNode.event);
+            insightSet = insights.values().find(set => Trace.Helpers.Timing.boundsIncludeTimeRange({
+                timeRange: callTreeTimeRange,
+                bounds: set.bounds,
+            })) ??
+                getFirstInsightSet(insights);
+        }
+        return new AgentFocus({ type: 'call-tree', parsedTrace: callTree.parsedTrace, insightSet, callTree });
+    }
+    #data;
+    constructor(data) {
+        this.#data = data;
+    }
+    get data() {
+        return this.#data;
+    }
+}
+export function getPerformanceAgentFocusFromModel(model) {
+    const parsedTrace = model.parsedTrace();
+    if (!parsedTrace) {
+        return null;
+    }
+    return AgentFocus.full(parsedTrace);
+}

package/build/node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIQueries.js

@@ -0,0 +1,105 @@
+// Copyright 2025 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+import * as Trace from '../../../models/trace/trace.js';
+import { AICallTree } from './AICallTree.js';
+export class AIQueries {
+    static findMainThread(navigationId, parsedTrace) {
+        /**
+         * We cannot assume that there is one main thread as there are scenarios
+         * where there can be multiple (see crbug.com/402658800) as an example.
+         * Therefore we calculate the main thread by using the thread that the
+         * Insight has been associated to. Most Insights relate to a navigation, so
+         * in this case we can use the navigation's PID/TID as we know that will
+         * have run on the main thread that we are interested in.
+         * If we do not have a navigation, we fall back to looking for the first
+         * thread we find that is of type MAIN_THREAD.
+         * Longer term we should solve this at the Trace Engine level to avoid
+         * look-ups like this; this is the work that is tracked in
+         * crbug.com/402658800.
+         */
+        let mainThreadPID = null;
+        let mainThreadTID = null;
+        if (navigationId) {
+            const navigation = parsedTrace.data.Meta.navigationsByNavigationId.get(navigationId);
+            if (navigation?.args.data?.isOutermostMainFrame) {
+                mainThreadPID = navigation.pid;
+                mainThreadTID = navigation.tid;
+            }
+        }
+        const threads = Trace.Handlers.Threads.threadsInTrace(parsedTrace.data);
+        const thread = threads.find(thread => {
+            if (mainThreadPID && mainThreadTID) {
+                return thread.pid === mainThreadPID && thread.tid === mainThreadTID;
+            }
+            return thread.type === "MAIN_THREAD" /* Trace.Handlers.Threads.ThreadType.MAIN_THREAD */;
+        });
+        return thread ?? null;
+    }
+    /**
+     * Returns bottom up activity for the given range.
+     */
+    static mainThreadActivityBottomUp(navigationId, bounds, parsedTrace) {
+        const thread = this.findMainThread(navigationId, parsedTrace);
+        if (!thread) {
+            return null;
+        }
+        const events = AICallTree.findEventsForThread({ thread, parsedTrace, bounds });
+        if (!events) {
+            return null;
+        }
+        // Use the same filtering as front_end/panels/timeline/TimelineTreeView.ts.
+        const visibleEvents = Trace.Helpers.Trace.VISIBLE_TRACE_EVENT_TYPES.values().toArray();
+        const filter = new Trace.Extras.TraceFilter.VisibleEventsFilter(visibleEvents.concat(["SyntheticNetworkRequest" /* Trace.Types.Events.Name.SYNTHETIC_NETWORK_REQUEST */]));
+        // The bottom up root node handles all the "in Tracebounds" checks we need for the insight.
+        const startTime = Trace.Helpers.Timing.microToMilli(bounds.min);
+        const endTime = Trace.Helpers.Timing.microToMilli(bounds.max);
+        return new Trace.Extras.TraceTree.BottomUpRootNode(events, {
+            textFilter: new Trace.Extras.TraceFilter.ExclusiveNameFilter([]),
+            filters: [filter],
+            startTime,
+            endTime,
+        });
+    }
+    /**
+     * Returns an AI Call Tree representing the activity on the main thread for
+     * the relevant time range of the given insight.
+     */
+    static mainThreadActivityTopDown(navigationId, bounds, parsedTrace) {
+        const thread = this.findMainThread(navigationId, parsedTrace);
+        if (!thread) {
+            return null;
+        }
+        return AICallTree.fromTimeOnThread({
+            thread: {
+                pid: thread.pid,
+                tid: thread.tid,
+            },
+            parsedTrace,
+            bounds,
+        });
+    }
+    /**
+     * Returns the top longest tasks as AI Call Trees.
+     */
+    static longestTasks(navigationId, bounds, parsedTrace, limit = 3) {
+        const thread = this.findMainThread(navigationId, parsedTrace);
+        if (!thread) {
+            return null;
+        }
+        const tasks = AICallTree.findMainThreadTasks({ thread, parsedTrace, bounds });
+        if (!tasks) {
+            return null;
+        }
+        const topTasks = tasks.filter(e => e.name === 'RunTask').sort((a, b) => b.dur - a.dur).slice(0, limit);
+        return topTasks
+            .map(task => {
+            const tree = AICallTree.fromEvent(task, parsedTrace);
+            if (tree) {
+                tree.selectedNode = null;
+            }
+            return tree;
+        })
+            .filter(tree => !!tree);
+    }
+}