chrome-devtools-frontend 1.0.1675430 → 1.0.1678416

package/front_end/models/ai_assistance/contexts/StorageContext.ts

@@ -0,0 +1,100 @@
+// Copyright 2026 The Chromium Authors
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+
+import {
+  ConversationContext,
+  type ConversationSuggestions,
+} from '../agents/AiAgent.js';
+import {CookieItem, DOMStorageItem, type StorageItem} from '../StorageItem.js';
+
+export class StorageContext extends ConversationContext<StorageItem> {
+  #item: StorageItem;
+
+  constructor(item: StorageItem) {
+    super();
+    this.#item = item;
+  }
+
+  override getURL(): string {
+    return this.#item.primaryTargetOrigin;
+  }
+
+  override getItem(): StorageItem {
+    return this.#item;
+  }
+
+  override getTitle(): string {
+    if (this.#item instanceof CookieItem) {
+      if (this.#item.name) {
+        return `cookie: ${this.#item.name}${this.#item.origin ? ` ${this.#item.origin}` : ''}`;
+      }
+      return `cookies${this.#item.isGenericContext ? '' : `: ${this.#item.origin}`}`;
+    }
+    if (this.#item instanceof DOMStorageItem) {
+      if (this.#item.key) {
+        return `entry: ${this.#item.key}${this.#item.origin ? ` ${this.#item.origin}` : ''}`;
+      }
+      const prefix = this.#item.type === 'localStorage' ? 'local storage' : 'session storage';
+      return `${prefix}${this.#item.isGenericContext ? '' : `: ${this.#item.origin}`}`;
+    }
+    return `Storage: ${this.getOrigin()}`;
+  }
+
+  /**
+   * @override
+   */
+  override isLoggingEnabled(): boolean {
+    if (this.#item instanceof CookieItem && Boolean(this.#item.name)) {
+      return false;
+    }
+    if (this.#item instanceof DOMStorageItem && Boolean(this.#item.key)) {
+      return false;
+    }
+    return true;
+  }
+
+  override async getSuggestions(): Promise<ConversationSuggestions|undefined> {
+    if (this.#item instanceof CookieItem) {
+      if (this.#item.name) {
+        return [
+          {
+            title: 'Why is this cookie set?',
+            jslogContext: 'storage-cookie',
+          },
+          {
+            title: 'Explain the value of this cookie',
+            jslogContext: 'storage-cookie',
+          },
+        ];
+      }
+      return [
+        {
+          title: 'Explain the cookies set by this page',
+          jslogContext: 'storage-cookie',
+        },
+      ];
+    }
+    if (this.#item instanceof DOMStorageItem) {
+      if (this.#item.key) {
+        return [
+          {
+            title: 'What is the purpose of this storage entry?',
+            jslogContext: 'storage-domstorage',
+          },
+          {
+            title: 'Explain the value of this storage entry',
+            jslogContext: 'storage-domstorage',
+          },
+        ];
+      }
+      return [
+        {
+          title: 'Explain these storage items',
+          jslogContext: 'storage-domstorage',
+        },
+      ];
+    }
+    return undefined;
+  }
+}

package/front_end/models/ai_assistance/data_formatters/PerformanceTraceFormatter.ts

@@ -11,7 +11,7 @@ import type {AICallTree} from '../performance/AICallTree.js';
 import type {AgentFocus} from '../performance/AIContext.js';
 import {AIQueries} from '../performance/AIQueries.js';
 
-import {NetworkRequestFormatter} from './NetworkRequestFormatter.js';
+import {NetworkRequestFormatter, sanitizeHeaders} from './NetworkRequestFormatter.js';
 import {PerformanceInsightFormatter} from './PerformanceInsightFormatter.js';
 import {bytes, micros, millis} from './UnitFormatters.js';
 
@@ -1036,3 +1036,71 @@ The order of headers corresponds to an internal fixed list. If a header is not p
     ].join('\n\n');
   }
 }
+
+/**
+ * Serializes a trace event to a JSON string for AI consumption,
+ * ensuring sensitive data (like headers and raw script source code)
+ * is sanitized or redacted.
+ */
+export function formatEventForAI(event: Trace.Types.Events.Event): string {
+  if (Trace.Types.Events.isSyntheticNetworkRequest(event)) {
+    return JSON.stringify({
+      ...event,
+      args: {
+        ...event.args,
+        data: {
+          ...event.args.data,
+          responseHeaders: event.args.data.responseHeaders ? sanitizeHeaders(event.args.data.responseHeaders) : null,
+        },
+      },
+    });
+  }
+
+  if (Trace.Types.Events.isResourceReceiveResponse(event)) {
+    return JSON.stringify({
+      ...event,
+      args: {
+        ...event.args,
+        data: {
+          ...event.args.data,
+          headers: event.args.data.headers ? sanitizeHeaders(event.args.data.headers) : undefined,
+        },
+      },
+    });
+  }
+
+  if (Trace.Types.Events.isRundownScriptSource(event)) {
+    // Redact sensitive cross-origin script source text.
+    const safeData: Omit<Trace.Types.Events.RundownScriptSource['args']['data'], 'sourceText'> = {
+      isolate: event.args.data.isolate,
+      scriptId: event.args.data.scriptId,
+      length: event.args.data.length,
+    };
+    return JSON.stringify({
+      ...event,
+      args: {
+        ...event.args,
+        data: safeData,
+      },
+    });
+  }
+
+  if (Trace.Types.Events.isRundownScriptSourceLarge(event)) {
+    // Redact sensitive cross-origin script source text.
+    const safeData: Omit<Trace.Types.Events.RundownScriptSourceLarge['args']['data'], 'sourceText'> = {
+      isolate: event.args.data.isolate,
+      scriptId: event.args.data.scriptId,
+      splitIndex: event.args.data.splitIndex,
+      splitCount: event.args.data.splitCount,
+    };
+    return JSON.stringify({
+      ...event,
+      args: {
+        ...event.args,
+        data: safeData,
+      },
+    });
+  }
+
+  return JSON.stringify(event);
+}

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

@@ -10,7 +10,7 @@ Example:
 ```markdown
 ---
 name: styling
-allowed-tools: [search_web]
+allowed-tools: [executeJavaScript]
 ---
 You are a CSS expert...
 ```
@@ -38,3 +38,65 @@ To use a skill in TypeScript:
 2.  Register it in `SkillRegistry.ts`.
 
 Types are provided globally in `front_end/global_typings/global_defs.d.ts` via a wildcard module declaration (`*.skill.js`). This avoids the need to generate `tsconfig.json` files for the generated skills.
+
+## Building a skill for AIv2
+
+_Note: some of this is a bit rough around the edges and subject to change as we build V2 out._
+
+If you want to add a new skill to DevTools AI v2 you should:
+
+Firstly, consider if we need it or not. Can we test the AI to see how it can handle relevant prompts without a new skill? (We are currently working on eval architecture to make this easier in the future too).
+
+Assuming we do want it, then we should create the new skill in `models/ai_assistance/skills/<NAME>.md`.
+
+This skill must have YAML frontmatter that defines its name and description, and optionally any tools that it is allowed to call (more on tools below):
+
+```
+---
+name: performance
+description: Web performance analysis, trace inspection, and trace recording.
+allowed-tools:
+  - recordPerformanceTrace
+---
+
+<body of the skill goes here>
+```
+
+The name and description are important. These are given to the AI in its context window so it knows that this tool exists and understands when to use it. You should think carefully about producing a very clear description and ideally evaluate this to check if the AI uses the tool in the right scenarios.
+
+To have the skill built as JavaScript and available to the AI:
+
+1. Update `models/ai_assistance/skills/BUILD.gn` to add the new skill file as a source.
+2. Update `models/ai_assistance/skills/Skill.ts` to add the new skill name to the `SkillName` union type.
+3. Update `models/ai_assistance/skills/SkillRegistry.ts` to import the generated skill file and register it in the `SKILLS` object.
+4. Add the generated skill file (`front_end/models/ai_assistance/skills/<NAME>.skill.js`) to the list of release sources in `config/gni/devtools_grd_files.gni`.
+
+If your skill does not need to call any tools, then you are done. The AI can now learn your skill and use it.
+
+### Using existing tools
+
+If your new skill needs to use tools that are already implemented:
+
+1. **Find the tool name**: Locate the tool's registration name in the `ToolName` enum (e.g., `executeJavaScript`, `listNetworkRequests`, `getStyles`) from `models/ai_assistance/tools/Tool.ts`.
+2. **Bind the tool to the skill**: Add the tool name to the `allowed-tools` list in your skill's Markdown frontmatter:
+   ```yaml
+   ---
+   name: my-skill
+   allowed-tools:
+     - executeJavaScript
+   ---
+   ```
+
+By doing this you ensure that if the AI learns you skill, those functions are learned and added to the active conversation for the AI to invoke.
+
+Even if other skills list the tool you need, you should list it also. Tools are not learned more than once; any subsequent skills that use the same tool do not cause it to be redeclared.
+
+### Implementing and binding tools
+
+If your new skill requires tools that do not exist yet, you should:
+
+1. Implement your new tool under `models/ai_assistance/tools/` extending the `BaseTool` class and implementing the `Tool` interface. Use the existing tools as guidance.
+2. Register the tool in the build system:
+   - Add the tool's source file to the `sources` list in `models/ai_assistance/BUILD.gn`.
+   - Import and register it inside `models/ai_assistance/tools/ToolRegistry.ts`.
+3. List the tool's name under the `allowed-tools` section of your skill's markdown frontmatter.

package/front_end/models/ai_assistance/skills/Skill.ts

@@ -3,7 +3,7 @@
 // found in the LICENSE file.
 
 // This will become a union type as we add more skills (e.g. 'styling' | 'network').
-export type SkillName = 'styling'|'network'|'accessibility'|'performance';
+export type SkillName = 'styling'|'network'|'accessibility'|'performance'|'storage'|'sources';
 
 export interface Skill {
   name: SkillName;

package/front_end/models/ai_assistance/skills/SkillRegistry.ts

@@ -6,6 +6,8 @@ import {skill as accessibilitySkill} from './accessibility.skill.js';
 import {skill as networkSkill} from './network.skill.js';
 import {skill as performanceSkill} from './performance.skill.js';
 import type {Skill, SkillName} from './Skill.js';
+import {skill as sourcesSkill} from './sources.skill.js';
+import {skill as storageSkill} from './storage.skill.js';
 import {skill as stylingSkill} from './styling.skill.js';
 
 export const SKILLS: Record<SkillName, Skill> = {
@@ -13,4 +15,6 @@ export const SKILLS: Record<SkillName, Skill> = {
   network: networkSkill,
   accessibility: accessibilitySkill,
   performance: performanceSkill,
+  storage: storageSkill,
+  sources: sourcesSkill,
 };

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

@@ -6,6 +6,8 @@ allowed-tools:
   - resolveDevtoolsNodePath
   - getStyles
   - getElementAccessibilityDetails
+  - runLighthouse
+  - executeJavaScript
 ---
 You are an expert accessibility debugging assistant.
 Use getLighthouseAudits to query details from the active report.
@@ -13,3 +15,8 @@ Use getLighthouseAudits to query details from the active report.
 * ALWAYS use resolveDevtoolsNodePath to resolve failing element paths to backend node IDs.
 * Once resolved, use getStyles on the backend node ID to inspect layout and styling properties.
 * Use getElementAccessibilityDetails to query detailed accessibility properties (ARIA properties, role, name, focus state) for a resolved element backend node ID.
+* If the user explicitly specifies a Lighthouse mode (e.g. "snapshot", "timespan", or "navigation"), ALWAYS honor the requested mode.
+* When running an initial audit (and no specific mode was requested), use runLighthouse with mode "navigation" for comprehensive page load coverage.
+* When re-auditing after in-page DOM/CSS modifications or fixes, use mode "snapshot" to evaluate live page state without reloading (noting that fewer audits run in snapshot mode).
+* Use mode "timespan" for measuring user interaction periods.
+* Use executeJavaScript to run layout/interaction scripts to verify fixes or dynamic accessibility behaviors.

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

@@ -3,8 +3,22 @@ name: performance
 description: Web performance analysis, trace inspection, and trace recording.
 allowed-tools:
   - recordPerformanceTrace
+  - getTraceEventByKey
+  - selectTraceEventByKey
+  - getTraceMainThreadSummary
+  - getTraceNetworkSummary
+  - getDetailedCallTree
+  - getFunctionCode
+  - getResourceContent
 ---
 You are an expert web performance assistant integrated into Chrome DevTools.
 Your goal is to help users analyze, measure, and improve web page performance.
 
-Use `recordPerformanceTrace` to record a new performance trace when requested by the user or when live measurement is required.
+- Use `recordPerformanceTrace` to record a new performance trace when requested by the user or when live measurement is required.
+- Trace events in the provided insights or summaries may have an `eventKey`. Use `getTraceEventByKey` with this key to retrieve detailed event data for verification.
+- If the user asks to see, locate, or show a specific event, use `selectTraceEventByKey` to reveal and select it in the Flamechart.
+- Use `getTraceMainThreadSummary` with a section label to get a bottom-up activity summary of the main thread for a specific labeled period.
+- Use `getTraceNetworkSummary` to get a summary of network requests within a specific microsecond time range.
+- Use `getDetailedCallTree` with an `eventKey` to retrieve the detailed call tree for a specific main thread trace event.
+- Use `getFunctionCode` with a script URL, line, and column to view annotated runtime performance of a function.
+- Use `getResourceContent` with a resource URL to inspect text resource or script contents for further root-cause analysis.

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

@@ -0,0 +1,16 @@
+---
+name: sources
+description: Analyzing workspace sources, inspecting code files, reading script contents, and viewing files in the workspace.
+allowed-tools:
+  - listSources
+  - getSourceContent
+---
+You are the most advanced source code analysis and debugging assistant integrated into Chrome DevTools.
+Provide a comprehensive analysis of source files, focusing on areas crucial for a software engineer. Your analysis should include:
+* Briefly explain the purpose and architecture of the file or script.
+* Analyze code blocks to identify potential bugs, logic issues, or areas for optimization.
+* Walk through execution flow if requested, pointing to key lines or functions.
+
+# Considerations
+* Never leak sensitive user data or API keys found in source code files. Redact or generalize them in your analysis.
+* Provide clean code snippets and direct line references where helpful.

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

@@ -0,0 +1,31 @@
+---
+name: storage
+description: inspect, understand, and audit the state stored in browser storage (LocalStorage, SessionStorage) or cookies.
+allowed-tools:
+  - listPageOrigins
+---
+You are a Senior Software Engineer specializing in state audit and storage analysis within Chrome DevTools. Your mission is to help developers debug storage-related issues faster by analyzing the evidence in LocalStorage, SessionStorage, and Cookies.
+
+You have access to the site's storage using tools.
+
+# Goals
+
+1.  **Explain Purpose**: Identify what specific storage entries or cookies are for.
+2.  **Understand Application State**: Help users inspect, understand, and audit the state stored in browser storage or cookies, and how it relates to application behavior or issues (such as state mismatch/drift, security misconfigurations, or oversized cookies).
+3.  **Top-Level Page First**: Your primary goal is to assist the user in understanding and debugging the storage of the **top-level page**. This context is the most critical for debugging and should be your default starting point for any analysis.
+
+# Tools & Workflow
+
+-   **Top-Level Context**: Generally, questions refer to the primary page target ("my page", "this page", etc.). If the user selects a general category or a specific selection, answers should refer to that particular selection, but follow-up questions may switch to the primary page target.
+-   **Address Specific Selections**: The user can select individual storage items in the DevTools UI (provided in the '# Active Context' section of the prompt). If the query is about a selected item (e.g., "Why is this cookie set?"), focus your response on that specific item.
+-   **General Category Selection**: If a general storage category (such as Cookies, Local Storage, or Session Storage) is selected in the active context (indicated by an empty context origin), your first step MUST be to look through all active page origins by calling `listPageOrigins` to discover origins, unless the user's explicit request hints otherwise.
+-   **Expand Scope When Necessary**: For general questions or those implying a wider scope (e.g., "Check all storages," "Are there related cookies on subdomains?"), proactively use your tools to explore other relevant storage contexts, including iframes and different origins.
+-   **Discovery**: Start by calling `listPageOrigins` to discover all active, non-empty frame origins loaded by the page.
+-   **Active Context**: Start by inspecting the active context's origin (provided in the '# Active Context' section of the prompt).
+
+# Considerations
+
+-   **Strictly Read-Only**: You cannot write, clear, delete, or edit storage or cookies.
+-   **DevTools UI Fallback**: If the user asks you to modify state, politely decline and provide exact step-by-step visual navigation directions on how they can perform the edit manually in the DevTools Application panel. Do NOT supply Console scripts.
+-   **Raw Evidence**: Treat storage data as raw evidence. Do not make assumptions about values without reading them first.
+-   **Dynamic State**: Always re-request values if you suspect they might have changed, rather than relying on past tool outputs.

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

@@ -0,0 +1,107 @@
+// Copyright 2026 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 Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Trace from '../../trace/trace.js';
+import {PerformanceTraceContext} from '../contexts/PerformanceTraceContext.js';
+import {AICallTree} from '../performance/AICallTree.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  lookingAtCallTree: 'Looking at call tree',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetDetailedCallTreeArgs extends ToolArgs {
+  eventKey: string;
+}
+
+export class GetDetailedCallTreeTool implements DataTool<GetDetailedCallTreeArgs, string, BaseToolCapability> {
+  readonly name = ToolName.GET_DETAILED_CALL_TREE;
+  readonly description = 'Returns a detailed call tree for the given main thread event.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetDetailedCallTreeArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for looking up a call tree.',
+    nullable: false,
+    properties: {
+      eventKey: {
+        type: Host.AidaClient.ParametersTypes.STRING,
+        description: 'The key for the event.',
+        nullable: false,
+      },
+    },
+    required: ['eventKey'],
+  };
+
+  displayInfoFromArgs(params: GetDetailedCallTreeArgs): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString(UIStringsNotTranslate.lookingAtCallTree),
+      action: `getDetailedCallTree('${params.eventKey}')`,
+    };
+  }
+
+  async handler(
+      params: GetDetailedCallTreeArgs,
+      capabilities: BaseToolCapability,
+      ): Promise<DataHandlerResult<string>> {
+    const conversationContext = capabilities.conversationContext;
+    if (!conversationContext || !(conversationContext instanceof PerformanceTraceContext)) {
+      return {error: 'Performance trace context is not available.'};
+    }
+
+    if (!params.eventKey) {
+      return {error: 'Missing arg: eventKey'};
+    }
+
+    const focus = conversationContext.getItem();
+    const event = focus.lookupEvent(params.eventKey);
+    if (!event) {
+      return {error: 'Invalid eventKey'};
+    }
+
+    const tree = AICallTree.fromEvent(event, focus.parsedTrace);
+    if (!tree) {
+      return {error: 'No call tree found'};
+    }
+
+    const formatter = conversationContext.createFormatter();
+    const callTree = await formatter.formatCallTree(tree);
+
+    const bounds = Trace.Helpers.Timing.traceWindowFromEvent(event);
+
+    return {
+      result: callTree,
+      widgets: [
+        {
+          name: 'BOTTOM_UP_TREE',
+          data: {
+            bounds,
+            parsedTrace: focus.parsedTrace,
+          },
+        },
+        {
+          name: 'TIMELINE_RANGE_SUMMARY',
+          data: {
+            bounds,
+            parsedTrace: focus.parsedTrace,
+            track: 'main',
+          },
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,122 @@
+// Copyright 2026 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 Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
+import type * as Platform from '../../../core/platform/platform.js';
+import {canResourceContentsBeReadForTrace} from '../AiOrigins.js';
+import {PerformanceTraceContext} from '../contexts/PerformanceTraceContext.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  lookingUpFunctionCode: 'Looking up function code',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetFunctionCodeArgs extends ToolArgs {
+  scriptUrl: string;
+  line: number;
+  column: number;
+}
+
+export class GetFunctionCodeTool implements DataTool<GetFunctionCodeArgs, string, BaseToolCapability> {
+  readonly name = ToolName.GET_FUNCTION_CODE;
+  readonly description =
+      'Returns the code for a function defined at the given location. The result is annotated with the runtime performance of each line of code.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetFunctionCodeArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for looking up function code.',
+    nullable: false,
+    properties: {
+      scriptUrl: {
+        type: Host.AidaClient.ParametersTypes.STRING,
+        description: 'The url of the function.',
+        nullable: false,
+      },
+      line: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The line number where the function is defined.',
+        nullable: false,
+      },
+      column: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The column number where the function is defined.',
+        nullable: false,
+      },
+    },
+    required: ['scriptUrl', 'line', 'column'],
+  };
+
+  displayInfoFromArgs(params: GetFunctionCodeArgs): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString(UIStringsNotTranslate.lookingUpFunctionCode),
+      action: `getFunctionCode('${params.scriptUrl}', ${params.line}, ${params.column})`,
+    };
+  }
+
+  async handler(
+      params: GetFunctionCodeArgs,
+      capabilities: BaseToolCapability,
+      ): Promise<DataHandlerResult<string>> {
+    const conversationContext = capabilities.conversationContext;
+    if (!conversationContext || !(conversationContext instanceof PerformanceTraceContext)) {
+      return {error: 'Performance trace context is not available.'};
+    }
+
+    if (conversationContext.getOrigin().startsWith('imported-trace://')) {
+      return {error: 'Cannot use this tool on an imported file.'};
+    }
+
+    if (!params.scriptUrl) {
+      return {error: 'Missing arg: scriptUrl'};
+    }
+
+    const allowedOrigin = conversationContext.getOrigin();
+    if (!canResourceContentsBeReadForTrace(params.scriptUrl, allowedOrigin)) {
+      return {error: 'Script not found'};
+    }
+
+    if (params.line === undefined) {
+      return {error: 'Missing arg: line'};
+    }
+
+    if (params.column === undefined) {
+      return {error: 'Missing arg: column'};
+    }
+
+    const formatter = conversationContext.createFormatter();
+    const url = params.scriptUrl as Platform.DevToolsPath.UrlString;
+    const code = await formatter.resolveFunctionCodeAtLocation(url, params.line, params.column);
+    if (!code) {
+      return {error: 'Could not find code'};
+    }
+
+    const result = formatter.formatFunctionCode(code);
+
+    return {
+      result,
+      widgets: [{
+        name: 'SOURCE_CODE',
+        data: {
+          url,
+          line: params.line,
+          column: params.column,
+          code: code.code,
+        },
+      }],
+    };
+  }
+}