chrome-devtools-frontend 1.0.1669021 → 1.0.1672557

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

@@ -5,10 +5,58 @@
 import type * as Host from '../../../core/host/host.js';
 import type * as SDK from '../../../core/sdk/sdk.js';
 import type * as LHModel from '../../lighthouse/lighthouse.js';
-import type {ConversationContext, FunctionCallHandlerResult, FunctionHandlerOptions} from '../agents/AiAgent.js';
+import type * as Trace from '../../trace/trace.js';
+import type {AiWidget, ConversationContext, FunctionHandlerOptions} from '../agents/AiAgent.js';
 import type {executeJsCode} from '../agents/ExecuteJavascript.js';
 import type {ChangeManager} from '../ChangeManager.js';
 
+/**
+ * Result indicating an error occurred during tool execution.
+ */
+export interface ToolErrorResult {
+  error: string;
+}
+
+/**
+ * Result indicating user approval is required before running the tool.
+ */
+export interface ToolApprovalResult {
+  requiresApproval: true;
+  description: string|null;
+}
+
+/**
+ * Result produced by a DataTool (`DataTool`). Contains a structured data payload (`result`)
+ * returned to answer the AI query without altering the conversation's active focus target.
+ * May optionally include UI widgets to render in the panel.
+ */
+export interface ToolDataResult<DataType> {
+  result: DataType;
+  widgets?: AiWidget[];
+}
+
+/**
+ * Result produced by a ContextTool (`ContextTool`). Switches or introduces a new active focal entity
+ * (`context`) into the conversation session (e.g., attaching a performance trace or selecting a DOM node)
+ * along with a human-readable `description` explaining the context switch and optional UI widgets.
+ */
+export interface ToolContextResult<ContextType = unknown> {
+  context: ConversationContext<ContextType>;
+  description: string;
+  widgets?: AiWidget[];
+}
+
+/**
+ * Union for tools that produce data output (`DataTool`).
+ */
+export type DataHandlerResult<DataType> = ToolDataResult<DataType>|ToolApprovalResult|ToolErrorResult;
+
+/**
+ * Union for tools that switch or return conversation context (`ContextTool`).
+ */
+export type ContextHandlerResult<ContextType = unknown> =
+    ToolContextResult<ContextType>|ToolApprovalResult|ToolErrorResult;
+
 /**
  * Base capability for all tool contexts, providing access to the conversation context.
  */
@@ -80,12 +128,19 @@ export interface LighthouseCapability {
   lighthouseRecording?: (overrides?: LHModel.RunTypes.RunOverrides) => Promise<LHModel.ReporterTypes.ReportJSON|null>;
 }
 
+/**
+ * Capability for tools that need to record performance traces.
+ */
+export interface PerformanceRecordingCapability {
+  performanceRecordAndReload?: () => Promise<Trace.TraceModel.ParsedTrace>;
+}
+
 /**
  * Unified context interface providing all capabilities available in the project.
  * Used by the agent to pass a complete context to any tool type-safely.
  */
 export type AllToolsCapabilities = BaseToolCapability&PageExecutionCapability&StyleMutationCapability&TargetCapability&
-    OriginLockCapability&LighthouseCapability;
+    OriginLockCapability&LighthouseCapability&PerformanceRecordingCapability;
 
 /**
  * Base argument type for AI Tools.
@@ -100,51 +155,90 @@ export const enum ToolName {
   GET_LIGHTHOUSE_AUDITS = 'getLighthouseAudits',
   RESOLVE_DEVTOOLS_NODE_PATH = 'resolveDevtoolsNodePath',
   GET_ELEMENT_ACCESSIBILITY_DETAILS = 'getElementAccessibilityDetails',
+  RECORD_PERFORMANCE_TRACE = 'recordPerformanceTrace',
 }
 
 /**
- * Non-generic metadata interface for a Tool.
- * Used for storing and retrieving tools generically without type-erasure concerns.
+ * Base metadata interface for a Tool.
+ * Provides parameter schema and display info formatting for tool argument types.
+ *
+ * @template ArgsType The expected object schema for tool arguments. Defaults to `ToolArgs`.
  */
-export interface BaseTool {
+export interface BaseTool<ArgsType extends ToolArgs = ToolArgs> {
   readonly name: ToolName;
   readonly description: string;
   /**
    * JSON schema representing the parameters this tool accepts.
    */
-  readonly parameters: Host.AidaClient.FunctionObjectParam<string|number|symbol>;
-}
-
-/**
- * Main generic interface for defining a Tool.
- * Binds the parameter schema properties and the handler implementation to a strict `Args` and `ContextType` contract.
- *
- * @template Args - The expected object type for tool arguments. Must be an object type.
- * @template ReturnType - The type of data returned by the handler function.
- * @template ContextType - The interface defining the capabilities this tool requires. Defaults to `BaseToolCapability`.
- */
-export interface Tool<Args extends ToolArgs = ToolArgs, ReturnType = unknown,
-                                   ContextType extends BaseToolCapability = BaseToolCapability> extends BaseTool {
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof Args>;
+  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).
    */
   readonly displayInfoFromArgs?: (
-      args: Args,
+      args: ArgsType,
       ) => {
     title?: string, thought?: string, action?: string, suggestions?: [string, ...string[]],
   };
+}
+
+/**
+ * Generic tool interface for tools that process inputs and return structured data results.
+ *
+ * @template ArgsType The expected object schema for tool arguments.
+ * @template ReturnType The concrete type of data payload returned in the result.
+ * @template CapabilitiesType The capabilities interface required by this tool. Defaults to `BaseToolCapability`.
+ */
+export interface DataTool<
+    ArgsType extends ToolArgs = ToolArgs,
+    ReturnType = unknown,
+    CapabilitiesType extends BaseToolCapability = BaseToolCapability,
+    > extends BaseTool<ArgsType> {
+  /**
+   * The implementation function called when the AI invokes this tool.
+   *
+   * @param args The arguments provided by the AI model matching the tool's parameter schema.
+   * @param capabilities The context object providing the capabilities requested by `CapabilitiesType`.
+   * @param options Additional runtime options for the handler execution.
+   */
+  handler(
+      args: ArgsType,
+      capabilities: CapabilitiesType,
+      options?: FunctionHandlerOptions,
+      ): Promise<DataHandlerResult<ReturnType>>;
+}
+
+/**
+ * Generic tool interface for tools that yield a new `ConversationContext` rather than plain data.
+ *
+ * @template ArgsType The expected object schema for tool arguments.
+ * @template ContextClass The concrete item type wrapped by the returned `ConversationContext`.
+ * @template CapabilitiesType The capabilities interface required by this tool. Defaults to `BaseToolCapability`.
+ */
+export interface ContextTool<
+    ArgsType extends ToolArgs = ToolArgs,
+    ContextClass = unknown,
+    CapabilitiesType extends BaseToolCapability = BaseToolCapability,
+    > extends BaseTool<ArgsType> {
   /**
    * The implementation function called when the AI invokes this tool.
    *
    * @param args The arguments provided by the AI model matching the tool's parameter schema.
-   * @param context The context object providing the capabilities requested by `ContextType`.
+   * @param capabilities The context object providing the capabilities requested by `CapabilitiesType`.
    * @param options Additional runtime options for the handler execution.
    */
   handler(
-      args: Args,
-      context: ContextType,
+      args: ArgsType,
+      capabilities: CapabilitiesType,
       options?: FunctionHandlerOptions,
-      ): Promise<FunctionCallHandlerResult<ReturnType>>;
+      ): Promise<ContextHandlerResult<ContextClass>>;
 }
+
+/**
+ * Represents any AI Assistance tool: either a `DataTool` (returns data/widgets) or a `ContextTool` (switches active context).
+ */
+export type Tool<
+    ArgsType extends ToolArgs = ToolArgs,
+    ReturnType = unknown,
+    CapabilitiesType extends BaseToolCapability = BaseToolCapability,
+    > = DataTool<ArgsType, ReturnType, CapabilitiesType>|ContextTool<ArgsType, ReturnType, CapabilitiesType>;

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

@@ -8,6 +8,7 @@ import {GetLighthouseAuditsTool} from './GetLighthouseAudits.js';
 import {GetNetworkRequestDetailsTool} from './GetNetworkRequestDetails.js';
 import {GetStylesTool} from './GetStyles.js';
 import {ListNetworkRequestsTool} from './ListNetworkRequests.js';
+import {RecordPerformanceTraceTool} from './RecordPerformanceTrace.js';
 import {ResolveDevtoolsNodePathTool} from './ResolveDevtoolsNodePath.js';
 import {type AllToolsCapabilities, type Tool, type ToolArgs, ToolName} from './Tool.js';
 
@@ -27,6 +28,7 @@ export const TOOLS = {
   [ToolName.GET_LIGHTHOUSE_AUDITS]: new GetLighthouseAuditsTool(),
   [ToolName.RESOLVE_DEVTOOLS_NODE_PATH]: new ResolveDevtoolsNodePathTool(),
   [ToolName.GET_ELEMENT_ACCESSIBILITY_DETAILS]: new GetElementAccessibilityDetailsTool(),
+  [ToolName.RECORD_PERFORMANCE_TRACE]: new RecordPerformanceTraceTool(),
 };
 
 /**

package/front_end/models/badges/UserBadges.ts

@@ -92,7 +92,9 @@ export class UserBadges extends Common.ObjectWrapper.ObjectWrapper<EventTypes> {
       Root.DevToolsContext.globalInstance().set(
           UserBadges,
           new UserBadges(
+              // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
               Common.Settings.Settings.instance(),
+              // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
               Host.GdpClient.GdpClient.instance(),
               Host.InspectorFrontendHost.InspectorFrontendHostInstance,
               ),

package/front_end/models/bindings/NetworkProject.ts

@@ -120,6 +120,7 @@ export class NetworkProject {
     }
 
     const data = {uiSourceCode, frame};
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     NetworkProjectManager.instance().dispatchEventToListeners(Events.FRAME_ATTRIBUTION_ADDED, data);
   }
 
@@ -140,18 +141,22 @@ export class NetworkProject {
     }
     frameAttribution.delete(frameId);
     const data = {uiSourceCode, frame: attributionInfo.frame};
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     NetworkProjectManager.instance().dispatchEventToListeners(Events.FRAME_ATTRIBUTION_REMOVED, data);
   }
 
   static targetForUISourceCode(uiSourceCode: Workspace.UISourceCode.UISourceCode): SDK.Target.Target|null {
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     return NetworkProjectManager.instance().getTargetForUISourceCode(uiSourceCode);
   }
 
   static setTargetForProject(project: Workspace.Workspace.Project, target: SDK.Target.Target): void {
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     NetworkProjectManager.instance().setTargetForProject(project, target);
   }
 
   static getTargetForProject(project: Workspace.Workspace.Project): SDK.Target.Target|null {
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     return NetworkProjectManager.instance().getTargetForProject(project);
   }
 

package/front_end/models/bindings/ResourceScriptMapping.ts

@@ -408,6 +408,7 @@ export class ResourceScriptFile extends Common.ObjectWrapper.ObjectWrapper<Resou
     if (!exceptionDetails) {
       // TODO(crbug.com/1334484): Instead of to the console, report these errors in an "info bar" at the bottom
       //                          of the text editor, similar to e.g. source mapping errors.
+      // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
       Common.Console.Console.instance().addMessage(
           i18nString(UIStrings.liveEditFailed, {PH1: getErrorText(status)}), Common.Console.MessageLevel.WARNING);
       return;
@@ -508,6 +509,7 @@ export class ResourceScriptFile extends Common.ObjectWrapper.ObjectWrapper<Resou
     if (!this.script) {
       return;
     }
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     const {pluginManager} = DebuggerWorkspaceBinding.instance();
     pluginManager.setDebugInfoURL(this.script, debugInfoURL);
   }

package/front_end/models/bindings/ResourceUtils.ts

@@ -39,6 +39,7 @@ import type * as Protocol from '../../generated/protocol.js';
 import * as Workspace from '../workspace/workspace.js';
 
 export function resourceForURL(url: Platform.DevToolsPath.UrlString): SDK.Resource.Resource|null {
+  // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
   return SDK.ResourceTreeModel.ResourceTreeModel.resourceForURL(SDK.TargetManager.TargetManager.instance(), url);
 }
 
@@ -47,6 +48,7 @@ export function displayNameForURL(url: Platform.DevToolsPath.UrlString): string
     return '';
   }
 
+  // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
   const uiSourceCode = Workspace.Workspace.WorkspaceImpl.instance().uiSourceCodeForURL(url);
   if (uiSourceCode) {
     return uiSourceCode.displayName();
@@ -57,6 +59,7 @@ export function displayNameForURL(url: Platform.DevToolsPath.UrlString): string
     return resource.displayName;
   }
 
+  // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
   const inspectedURL = SDK.TargetManager.TargetManager.instance().inspectedURL();
   if (!inspectedURL) {
     return Platform.StringUtilities.trimURL(url, '');

package/front_end/models/crux-manager/CrUXManager.ts

@@ -166,6 +166,7 @@ export class CrUXManager extends Common.ObjectWrapper.ObjectWrapper<EventTypes>
     if (!Root.DevToolsContext.globalInstance().has(CrUXManager) || forceNew) {
       Root.DevToolsContext.globalInstance().set(
           CrUXManager,
+          // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
           new CrUXManager(SDK.TargetManager.TargetManager.instance(), Common.Settings.Settings.instance()));
     }
 

package/front_end/models/emulation/DeviceModeModel.ts

@@ -5,10 +5,13 @@
 import * as Common from '../../core/common/common.js';
 import * as Host from '../../core/host/host.js';
 import * as i18n from '../../core/i18n/i18n.js';
+import * as Platform from '../../core/platform/platform.js';
 import * as Root from '../../core/root/root.js';
 import * as SDK from '../../core/sdk/sdk.js';
+import * as TextUtils from '../../core/text_utils/text_utils.js';
 import * as Protocol from '../../generated/protocol.js';
 import * as Geometry from '../geometry/geometry.js';
+import * as Workspace from '../workspace/workspace.js';
 
 import {
   type Cutout,
@@ -196,12 +199,16 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
 
   static instance(opts?: {forceNew: boolean}): DeviceModeModel {
     if (!Root.DevToolsContext.globalInstance().has(DeviceModeModel) || opts?.forceNew) {
-      Root.DevToolsContext.globalInstance().set(DeviceModeModel,
-                                                new DeviceModeModel(
-                                                    SDK.TargetManager.TargetManager.instance(),
-                                                    Common.Settings.Settings.instance(),
-                                                    SDK.NetworkManager.MultitargetNetworkManager.instance(),
-                                                    ));
+      Root.DevToolsContext.globalInstance().set(
+          DeviceModeModel,
+          new DeviceModeModel(
+              // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+              SDK.TargetManager.TargetManager.instance(),
+              // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+              Common.Settings.Settings.instance(),
+              // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+              SDK.NetworkManager.MultitargetNetworkManager.instance(),
+              ));
     }
 
     return Root.DevToolsContext.globalInstance().get(DeviceModeModel);
@@ -444,6 +451,14 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     return this.#settings.createSetting('emulation.show-device-mode', false);
   }
 
+  isDeviceModeOn(): boolean {
+    return this.enabledSetting().get();
+  }
+
+  toggleDeviceMode(): void {
+    this.enabledSetting().set(!this.enabledSetting().get());
+  }
+
   scaleSetting(): Common.Settings.Setting<number> {
     return this.#scaleSetting;
   }
@@ -832,7 +847,7 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     }
   }
 
-  async captureScreenshot(fullSize: boolean, clip?: Protocol.Page.Viewport): Promise<string|null> {
+  async #captureScreenshot(fullSize: boolean, clip?: Protocol.Page.Viewport): Promise<string|null> {
     const screenCaptureModel =
         this.#emulationModel ? this.#emulationModel.target().model(SDK.ScreenCaptureModel.ScreenCaptureModel) : null;
     if (!screenCaptureModel) {
@@ -879,6 +894,124 @@ export class DeviceModeModel extends Common.ObjectWrapper.ObjectWrapper<EventTyp
     }
   }
 
+  async captureScreenshot(): Promise<void> {
+    const screenshot = await this.#captureScreenshot(false);
+    if (screenshot === null) {
+      return;
+    }
+
+    const pageImage = new Image();
+    pageImage.src = 'data:image/png;base64,' + screenshot;
+    pageImage.onload = async () => {
+      const scale = pageImage.naturalWidth / this.screenRect().width;
+      const outlineRectFromModel = this.outlineRect();
+      if (!outlineRectFromModel) {
+        throw new Error('Unable to take screenshot: no outlineRect available.');
+      }
+      const outlineRect = outlineRectFromModel.scale(scale);
+      const screenRect = this.screenRect().scale(scale);
+      const visiblePageRect = this.visiblePageRect().scale(scale);
+      const contentLeft = screenRect.left + visiblePageRect.left - outlineRect.left;
+      const contentTop = screenRect.top + visiblePageRect.top - outlineRect.top;
+
+      const canvas = new OffscreenCanvas(Math.floor(outlineRect.width),
+                                         // Cap the height to not hit the GPU limit.
+                                         // https://crbug.com/1260828
+                                         Math.min((1 << 14), Math.floor(outlineRect.height)));
+      const ctx = canvas.getContext('2d', {willReadFrequently: true});
+      if (!ctx) {
+        throw new Error('Could not get 2d context from canvas.');
+      }
+      ctx.imageSmoothingEnabled = false;
+
+      if (this.outlineImage()) {
+        await this.paintImage(ctx, this.outlineImage(), outlineRect.relativeTo(outlineRect));
+      }
+      if (this.screenImage()) {
+        await this.paintImage(ctx, this.screenImage(), screenRect.relativeTo(outlineRect));
+      }
+      ctx.drawImage(pageImage, Math.floor(contentLeft), Math.floor(contentTop));
+      void this.saveScreenshot(canvas);
+    };
+  }
+
+  async captureFullSizeScreenshot(): Promise<void> {
+    const screenshot = await this.#captureScreenshot(true);
+    if (screenshot === null) {
+      return;
+    }
+    return this.saveScreenshotBase64(screenshot);
+  }
+
+  async captureAreaScreenshot(clip?: Protocol.Page.Viewport): Promise<void> {
+    const screenshot = await this.#captureScreenshot(false, clip);
+    if (screenshot === null) {
+      return;
+    }
+    return this.saveScreenshotBase64(screenshot);
+  }
+
+  private saveScreenshotBase64(screenshot: string): void {
+    const pageImage = new Image();
+    pageImage.src = 'data:image/png;base64,' + screenshot;
+    pageImage.onload = () => {
+      const canvas = new OffscreenCanvas(pageImage.naturalWidth,
+                                         // Cap the height to not hit the GPU limit.
+                                         // https://crbug.com/1260828
+                                         Math.min((1 << 14), Math.floor(pageImage.naturalHeight)));
+      const ctx = canvas.getContext('2d', {willReadFrequently: true});
+      if (!ctx) {
+        throw new Error('Could not get 2d context for base64 screenshot.');
+      }
+      ctx.imageSmoothingEnabled = false;
+      ctx.drawImage(pageImage, 0, 0);
+      void this.saveScreenshot(canvas);
+    };
+  }
+
+  private paintImage(ctx: OffscreenCanvasRenderingContext2D|CanvasRenderingContext2D, src: string,
+                     rect: Rect): Promise<void> {
+    return new Promise(resolve => {
+      const image = new Image();
+      image.crossOrigin = 'Anonymous';
+      image.srcset = src;
+      image.onerror = () => resolve();
+      image.onload = () => {
+        ctx.drawImage(image, rect.left, rect.top, rect.width, rect.height);
+        resolve();
+      };
+    });
+  }
+
+  private async saveScreenshot(canvas: OffscreenCanvas): Promise<void> {
+    const url = this.inspectedURL();
+    let fileName = '';
+    if (url) {
+      const withoutFragment = Platform.StringUtilities.removeURLFragment(url);
+      fileName = Platform.StringUtilities.trimURL(withoutFragment);
+    }
+
+    const device = this.device();
+    if (device && this.type() === Type.Device) {
+      fileName += `(${device.title})`;
+    }
+    fileName += '.png';
+    const blob = await canvas.convertToBlob({type: 'image/png'});
+    const dataUrl = await new Promise<string>((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onloadend = () => resolve(reader.result as string);
+      reader.onerror = reject;
+      reader.readAsDataURL(blob);
+    });
+    const base64 = dataUrl.slice(dataUrl.indexOf(',') + 1);
+    const contentData = new TextUtils.ContentData.ContentData(base64, /* isBase64=*/ true, 'image/png');
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+    await Workspace.FileManager.FileManager.instance().save(fileName as Platform.DevToolsPath.RawPathString,
+                                                            contentData, /* forceSaveAs=*/ true);
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+    Workspace.FileManager.FileManager.instance().close(fileName as Platform.DevToolsPath.RawPathString);
+  }
+
   private applyTouch(touchEnabled: boolean, mobile: boolean): void {
     this.#touchEnabled = touchEnabled;
     this.#touchMobile = mobile;