(do not merge): exposing additional performance functions

This PR is so we have a branch that has the bigger set of performance
functions available to it that are equivalent to the ones the DevTools
Performance Agent has.

If we decide we want to expose these functions, we will do so via
reusing the implementation from upstream, not via the copy/paste of this
PR, but this is the quickest way to get them available to test.

Author: jackfranklin

src/tools/performance.ts

@@ -7,6 +7,10 @@
 import type {Page} from 'puppeteer-core';
 import z from 'zod';
 
+import {PerformanceTraceFormatter} from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.js';
+import {AICallTree} from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AICallTree.js';
+import {AgentFocus} from '../../node_modules/chrome-devtools-frontend/front_end/models/ai_assistance/performance/AIContext.js';
+import * as TraceEngine from '../../node_modules/chrome-devtools-frontend/front_end/models/trace/trace.js';
 import {logger} from '../logger.js';
 import type {InsightName} from '../trace-processing/parse.js';
 import {
@@ -189,3 +193,157 @@ async function stopTracingAndAppendOutput(
     context.setIsRunningPerformanceTrace(false);
   }
 }
+
+export const getEventByKey = defineTool({
+  name: 'performance_get_event_by_key',
+  description:
+    'Returns detailed information about a specific event. Use the detail returned to validate performance issues, but do not tell the user about irrelevant raw data from a trace event.',
+  annotations: {
+    category: ToolCategories.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {
+    eventKey: z.string().describe('The key for the event.'),
+  },
+  handler: async (request, response, context) => {
+    const trace = context.recordedTraces().at(-1);
+    if (!trace) {
+      response.appendResponseLine('Error: no trace recorded');
+      return;
+    }
+    const focus = AgentFocus.fromParsedTrace(trace.parsedTrace);
+    const event = focus.lookupEvent(
+      request.params.eventKey as TraceEngine.Types.File.SerializableKey,
+    );
+    if (!event) {
+      response.appendResponseLine('Error: no event with key found');
+      return;
+    }
+    response.appendResponseLine(`Event:\n${JSON.stringify(event, null, 2)}`);
+  },
+});
+
+export const getMainThreadTrackSummary = defineTool({
+  name: 'performance_get_main_thread_track_summary',
+  description:
+    'Returns a summary of the main thread for the given bounds. The result includes a top-down summary, bottom-up summary, third-parties summary, and a list of related insights for the events within the given bounds.',
+  annotations: {
+    category: ToolCategories.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {
+    min: z.number().describe('The minimum time of the bounds, in microseconds'),
+    max: z.number().describe('The maximum time of the bounds, in microseconds'),
+  },
+  handler: async (request, response, context) => {
+    const trace = context.recordedTraces().at(-1);
+    if (!trace) {
+      response.appendResponseLine('Error: no trace recorded');
+      return;
+    }
+    const bounds = createBounds(
+      trace.parsedTrace,
+      request.params.min as TraceEngine.Types.Timing.Micro,
+      request.params.max as TraceEngine.Types.Timing.Micro,
+    );
+    if (!bounds) {
+      response.appendResponseLine('Erorr: invalid trace bounds');
+      return;
+    }
+
+    const focus = AgentFocus.fromParsedTrace(trace.parsedTrace);
+    const formatter = new PerformanceTraceFormatter(focus);
+    response.appendResponseLine(formatter.formatMainThreadTrackSummary(bounds));
+  },
+});
+
+export const getNetworkTrackSummary = defineTool({
+  name: 'performance_get_network_track_summary',
+  description: 'Returns a summary of the network for the given bounds.',
+  annotations: {
+    category: ToolCategories.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {
+    min: z.number().describe('The minimum time of the bounds, in microseconds'),
+    max: z.number().describe('The maximum time of the bounds, in microseconds'),
+  },
+  handler: async (request, response, context) => {
+    const trace = context.recordedTraces().at(-1);
+    if (!trace) {
+      response.appendResponseLine('Error: no trace recorded');
+      return;
+    }
+    const bounds = createBounds(
+      trace.parsedTrace,
+      request.params.min as TraceEngine.Types.Timing.Micro,
+      request.params.max as TraceEngine.Types.Timing.Micro,
+    );
+    if (!bounds) {
+      response.appendResponseLine('Erorr: invalid trace bounds');
+      return;
+    }
+
+    const focus = AgentFocus.fromParsedTrace(trace.parsedTrace);
+    const formatter = new PerformanceTraceFormatter(focus);
+    response.appendResponseLine(formatter.formatNetworkTrackSummary(bounds));
+  },
+});
+
+export const getDetailedCallTree = defineTool({
+  name: 'performance_get_detailed_call_tree',
+  description: 'Returns a detailed call tree for the given main thread event.',
+  annotations: {
+    category: ToolCategories.PERFORMANCE,
+    readOnlyHint: true,
+  },
+  schema: {
+    eventKey: z.string().describe('The key for the event.'),
+  },
+  handler: async (request, response, context) => {
+    const trace = context.recordedTraces().at(-1);
+    if (!trace) {
+      response.appendResponseLine('Error: no trace recorded');
+      return;
+    }
+    const focus = AgentFocus.fromParsedTrace(trace.parsedTrace);
+    const event = focus.lookupEvent(
+      request.params.eventKey as TraceEngine.Types.File.SerializableKey,
+    );
+    if (!event) {
+      response.appendResponseLine('Error: no event with key found');
+      return;
+    }
+    const formatter = new PerformanceTraceFormatter(focus);
+    const tree = AICallTree.fromEvent(event, trace.parsedTrace);
+    const callTree = tree
+      ? formatter.formatCallTree(tree)
+      : 'No call tree found';
+    response.appendResponseLine(callTree);
+  },
+});
+
+const createBounds = (
+  trace: TraceEngine.TraceModel.ParsedTrace,
+  min: TraceEngine.Types.Timing.Micro,
+  max: TraceEngine.Types.Timing.Micro,
+): TraceEngine.Types.Timing.TraceWindowMicro | null => {
+  if (min > max) {
+    return null;
+  }
+
+  const clampedMin = Math.max(min ?? 0, trace.data.Meta.traceBounds.min);
+  const clampedMax = Math.min(
+    max ?? Number.POSITIVE_INFINITY,
+    trace.data.Meta.traceBounds.max,
+  );
+  if (clampedMin > clampedMax) {
+    return null;
+  }
+
+  return TraceEngine.Helpers.Timing.traceWindowFromMicroSeconds(
+    clampedMin as TraceEngine.Types.Timing.Micro,
+    clampedMax as TraceEngine.Types.Timing.Micro,
+  );
+};
+