chrome-devtools-frontend 1.0.1675430 → 1.0.1676824

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/GetSourceContent.ts

@@ -0,0 +1,101 @@
+// 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 Common from '../../../core/common/common.js';
+import * as Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as TextUtils from '../../../core/text_utils/text_utils.js';
+import {FileFormatter} from '../data_formatters/FileFormatter.js';
+
+import {ListSourcesTool} from './ListSources.js';
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type OriginLockCapability,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  readingSource: 'Reading source content',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetSourceContentArgs extends ToolArgs {
+  id: number;
+}
+
+/**
+ * A tool that retrieves the contents of a source file by its unique ID.
+ * Filters access by origin lock to prevent cross-origin leakage.
+ */
+export class GetSourceContentTool implements
+    DataTool<GetSourceContentArgs, {content: string}, BaseToolCapability&OriginLockCapability> {
+  readonly name = ToolName.GET_SOURCE_CONTENT;
+  readonly description = 'Gets the content and metadata of a source file by its ID.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetSourceContentArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: '',
+    properties: {
+      id: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The unique numeric ID of the source file to retrieve.',
+        nullable: false,
+      },
+    },
+    required: ['id'],
+  };
+
+  displayInfoFromArgs(args: GetSourceContentArgs): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString(UIStringsNotTranslate.readingSource),
+      action: `getSourceContent(${args.id})`,
+    };
+  }
+
+  async handler(
+      args: GetSourceContentArgs,
+      context: BaseToolCapability&OriginLockCapability,
+      ): Promise<DataHandlerResult<{content: string}>> {
+    const origin = context.getEstablishedOrigin();
+    const file = ListSourcesTool.getUISourceCodes().find(
+        f => ListSourcesTool.uiSourceCodeId.get(f) === args.id,
+    );
+
+    if (!file) {
+      return {
+        error: 'Unable to find file.',
+      };
+    }
+
+    const fileUrl = file.url();
+    const fileOrigin = Common.ParsedURL.ParsedURL.extractOrigin(fileUrl);
+    if (origin && fileOrigin !== origin) {
+      return {
+        error: 'Cross-origin access blocked.',
+      };
+    }
+
+    const contentData = await file.requestContentData();
+    if (TextUtils.ContentData.ContentData.isError(contentData)) {
+      return {
+        error: `Failed to load file content: ${contentData.error}`,
+      };
+    }
+
+    const formatter = new FileFormatter(file);
+
+    return {
+      result: {
+        content: formatter.formatFile(),
+      },
+    };
+  }
+}

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

@@ -0,0 +1,83 @@
+// 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 {PerformanceTraceContext} from '../contexts/PerformanceTraceContext.js';
+import {formatEventForAI} from '../data_formatters/PerformanceTraceFormatter.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  lookingAtTraceEvent: 'Looking at trace event',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetTraceEventByKeyArgs extends ToolArgs {
+  eventKey: string;
+}
+
+export class GetTraceEventByKeyTool implements DataTool<GetTraceEventByKeyArgs, string, BaseToolCapability> {
+  readonly name = ToolName.GET_TRACE_EVENT_BY_KEY;
+  readonly description = 'Get details for a specific trace event by its event key.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceEventByKeyArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for looking up a trace event.',
+    nullable: false,
+    properties: {
+      eventKey: {
+        type: Host.AidaClient.ParametersTypes.STRING,
+        description: 'The key of the event to look up.',
+        nullable: false,
+      },
+    },
+    required: ['eventKey'],
+  };
+
+  displayInfoFromArgs(params: GetTraceEventByKeyArgs): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString(UIStringsNotTranslate.lookingAtTraceEvent),
+      action: `getTraceEventByKey('${params.eventKey}')`,
+    };
+  }
+
+  async handler(
+      params: GetTraceEventByKeyArgs,
+      capabilities: BaseToolCapability,
+      ): Promise<DataHandlerResult<string>> {
+    const conversationContext = capabilities.conversationContext;
+    if (!conversationContext || !(conversationContext instanceof PerformanceTraceContext)) {
+      return {error: 'Performance trace context is not available.'};
+    }
+
+    const focus = conversationContext.getItem();
+    const event = focus.lookupEvent(params.eventKey);
+    if (!event) {
+      return {error: `Could not find event with key "${params.eventKey}".`};
+    }
+
+    const details = formatEventForAI(event);
+    return {
+      result: details,
+      widgets: [{
+        name: 'TIMELINE_EVENT_SUMMARY',
+        data: {
+          event,
+          parsedTrace: focus.parsedTrace,
+        },
+      }],
+    };
+  }
+}

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

@@ -0,0 +1,106 @@
+// 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 MainThreadSectionLabel,
+  PerformanceTraceContext,
+} from '../contexts/PerformanceTraceContext.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  MAX_FUNCTION_RESULT_BYTE_LENGTH,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  mainThreadActivity: 'Main thread activity',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetTraceMainThreadSummaryArgs extends ToolArgs {
+  label: MainThreadSectionLabel;
+}
+
+export class GetTraceMainThreadSummaryTool implements
+    DataTool<GetTraceMainThreadSummaryArgs, string, BaseToolCapability> {
+  readonly name = ToolName.GET_TRACE_MAIN_THREAD_SUMMARY;
+  readonly description = 'Returns a focused, detailed summary of the main thread for a predefined labeled period.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceMainThreadSummaryArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for looking up a main thread summary.',
+    nullable: false,
+    properties: {
+      label: {
+        type: Host.AidaClient.ParametersTypes.STRING,
+        description:
+            'The label of the period to investigate (e.g., \'LCPBreakdown\', \'CLSCulprits\', \'nav-to-lcp\').',
+        nullable: false,
+      },
+    },
+    required: ['label'],
+  };
+
+  displayInfoFromArgs(params: GetTraceMainThreadSummaryArgs): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: `${lockedString(UIStringsNotTranslate.mainThreadActivity)}: ${params.label}`,
+      action: `getTraceMainThreadSummary('${params.label}')`,
+    };
+  }
+
+  async handler(
+      params: GetTraceMainThreadSummaryArgs,
+      capabilities: BaseToolCapability,
+      ): Promise<DataHandlerResult<string>> {
+    const conversationContext = capabilities.conversationContext;
+    if (!conversationContext || !(conversationContext instanceof PerformanceTraceContext)) {
+      return {error: 'Performance trace context is not available.'};
+    }
+
+    const focus = conversationContext.getItem();
+    const bounds = conversationContext.getBoundsForLabel(params.label);
+    if (!bounds) {
+      return {error: `Invalid label: ${params.label}`};
+    }
+
+    const formatter = conversationContext.createFormatter();
+    const summary = await formatter.formatMainThreadTrackSummary(bounds);
+    if (summary.length > MAX_FUNCTION_RESULT_BYTE_LENGTH) {
+      return {
+        error:
+            'getTraceMainThreadSummary response is too large. Try investigating using other functions, or a more narrow bounds',
+      };
+    }
+
+    return {
+      result: summary,
+      widgets: [
+        {
+          name: 'TIMELINE_RANGE_SUMMARY',
+          data: {
+            parsedTrace: focus.parsedTrace,
+            bounds,
+            track: 'main',
+          },
+        },
+        {
+          name: 'BOTTOM_UP_TREE',
+          data: {
+            bounds,
+            parsedTrace: focus.parsedTrace,
+          },
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,104 @@
+// 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 {PerformanceTraceContext} from '../contexts/PerformanceTraceContext.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  MAX_FUNCTION_RESULT_BYTE_LENGTH,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  networkActivitySummary: 'Network activity summary',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+export interface GetTraceNetworkSummaryArgs extends ToolArgs {
+  min?: number;
+  max?: number;
+}
+
+export class GetTraceNetworkSummaryTool implements DataTool<GetTraceNetworkSummaryArgs, string, BaseToolCapability> {
+  readonly name = ToolName.GET_TRACE_NETWORK_SUMMARY;
+  readonly description = 'Returns a summary of the network requests for the given bounds.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceNetworkSummaryArgs> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: 'Arguments for looking up a network track summary.',
+    nullable: false,
+    properties: {
+      min: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The minimum time of the bounds, in microseconds.',
+        nullable: true,
+      },
+      max: {
+        type: Host.AidaClient.ParametersTypes.INTEGER,
+        description: 'The maximum time of the bounds, in microseconds.',
+        nullable: true,
+      },
+    },
+    required: [],
+  };
+
+  displayInfoFromArgs(params: GetTraceNetworkSummaryArgs): {
+    title: string,
+    action: string,
+  } {
+    const parts = [];
+    if (params.min !== undefined) {
+      parts.push(`min: ${params.min}`);
+    }
+    if (params.max !== undefined) {
+      parts.push(`max: ${params.max}`);
+    }
+    return {
+      title: lockedString(UIStringsNotTranslate.networkActivitySummary),
+      action: `getTraceNetworkSummary({${parts.join(', ')}})`,
+    };
+  }
+
+  async handler(
+      params: GetTraceNetworkSummaryArgs,
+      capabilities: BaseToolCapability,
+      ): Promise<DataHandlerResult<string>> {
+    const conversationContext = capabilities.conversationContext;
+    if (!conversationContext || !(conversationContext instanceof PerformanceTraceContext)) {
+      return {error: 'Performance trace context is not available.'};
+    }
+
+    const focus = conversationContext.getItem();
+    const bounds = conversationContext.createBounds(params.min, params.max);
+    if (!bounds) {
+      return {error: 'Invalid bounds.'};
+    }
+
+    const formatter = conversationContext.createFormatter();
+    const summary = formatter.formatNetworkTrackSummary(bounds);
+    if (summary.length > MAX_FUNCTION_RESULT_BYTE_LENGTH) {
+      return {
+        error:
+            'getTraceNetworkSummary response is too large. Try investigating using other functions, or a more narrow bounds',
+      };
+    }
+
+    return {
+      result: summary,
+      widgets: [{
+        name: 'NETWORK_TRACK',
+        data: {
+          parsedTrace: focus.parsedTrace,
+          bounds,
+        },
+      }],
+    };
+  }
+}

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

@@ -0,0 +1,81 @@
+// 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 Common from '../../../core/common/common.js';
+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 {areOriginsEquivalent, isOpaqueOrigin} from '../AiOrigins.js';
+import {isSamePageOrigin} from '../contexts/StorageContext.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type OriginLockCapability,
+  ToolName,
+} from './Tool.js';
+
+const lockedString = i18n.i18n.lockedString;
+
+export class ListPageOriginsTool implements
+    DataTool<Record<string, never>, {origins: string[]}, BaseToolCapability&OriginLockCapability> {
+  readonly name = ToolName.LIST_PAGE_ORIGINS;
+  readonly description =
+      'Lists all active, non-empty frame origins loaded by the page. Use this first when generic category context is active to discover all page origins, then pass them to listCookies or listStorageKeys, unless the user\'s explicit request hints at focusing only on the primary page.';
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<never> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: '',
+    nullable: false,
+    properties: {},
+    required: [],
+  };
+
+  displayInfoFromArgs(): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString('Listing page origins'),
+      action: 'listPageOrigins()',
+    };
+  }
+
+  async handler(
+      _args: Record<string, never>,
+      context: BaseToolCapability&OriginLockCapability,
+      ): Promise<DataHandlerResult<{origins: string[]}>> {
+    // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+    const targetManager = SDK.TargetManager.TargetManager.instance();
+    const primaryPageTarget = targetManager.primaryPageTarget();
+
+    const allowedOrigin = context.getEstablishedOrigin();
+    if (!allowedOrigin || isOpaqueOrigin(allowedOrigin)) {
+      return {error: 'No origin available or not allowed.'};
+    }
+
+    const pageOrigin =
+        primaryPageTarget ? Common.ParsedURL.ParsedURL.extractOrigin(primaryPageTarget.inspectedURL()) : '';
+    const isAllowed = pageOrigin !== '' && areOriginsEquivalent(pageOrigin, allowedOrigin);
+
+    if (!isAllowed) {
+      return {error: 'No origin available or not allowed.'};
+    }
+
+    const origins = new Set<string>();
+    for (const frame of SDK.ResourceTreeModel.ResourceTreeModel.frames(targetManager)) {
+      if (!isSamePageOrigin(frame.resourceTreeModel().target().outermostTarget(), allowedOrigin)) {
+        continue;
+      }
+      const origin = frame.securityOrigin;
+      if (!origin || isOpaqueOrigin(origin) || origins.has(origin)) {
+        continue;
+      }
+      origins.add(origin);
+    }
+
+    return {result: {origins: Array.from(origins)}};
+  }
+}

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

@@ -0,0 +1,116 @@
+// 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 Common from '../../../core/common/common.js';
+import * as Host from '../../../core/host/host.js';
+import * as i18n from '../../../core/i18n/i18n.js';
+import * as Workspace from '../../workspace/workspace.js';
+import {isOpaqueOrigin} from '../AiOrigins.js';
+
+import {
+  type BaseToolCapability,
+  type DataHandlerResult,
+  type DataTool,
+  type OriginLockCapability,
+  ToolName,
+} from './Tool.js';
+
+const UIStringsNotTranslate = {
+  listingSources: 'Listing workspace sources',
+} as const;
+
+const lockedString = i18n.i18n.lockedString;
+
+interface SourceSummary {
+  id: number;
+  name: string;
+}
+
+/**
+ * A tool that lists all network source files in the workspace.
+ * Each file is returned with its displayName and a unique session-based numeric ID.
+ */
+export class ListSourcesTool implements
+    DataTool<Record<string, never>, {files: SourceSummary[]}, BaseToolCapability&OriginLockCapability> {
+  readonly name = ToolName.LIST_SOURCES;
+  readonly description = 'Lists all source files in the workspace with their name and a unique ID.';
+
+  static lastSourceId = 0;
+  static uiSourceCodeId = new WeakMap<Workspace.UISourceCode.UISourceCode, number>();
+
+  static reset(): void {
+    ListSourcesTool.lastSourceId = 0;
+    ListSourcesTool.uiSourceCodeId = new WeakMap();
+  }
+
+  // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+  static getUISourceCodes(workspace: Workspace.Workspace.WorkspaceImpl = Workspace.Workspace.WorkspaceImpl.instance()):
+      Workspace.UISourceCode.UISourceCode[] {
+    const projects =
+        workspace.projects().filter(project => project.type() === Workspace.Workspace.projectTypes.Network);
+    const uiSourceCodes = new Map<string, Workspace.UISourceCode.UISourceCode>();
+
+    for (const project of projects) {
+      for (const uiSourceCode of project.uiSourceCodes()) {
+        if (uiSourceCode.isIgnoreListed()) {
+          continue;
+        }
+        const url = uiSourceCode.url();
+        if (!uiSourceCodes.get(url) || uiSourceCode.contentType().isFromSourceMap()) {
+          uiSourceCodes.set(url, uiSourceCode);
+          if (!ListSourcesTool.uiSourceCodeId.has(uiSourceCode)) {
+            ListSourcesTool.uiSourceCodeId.set(uiSourceCode, ++ListSourcesTool.lastSourceId);
+          }
+        }
+      }
+    }
+
+    return [...uiSourceCodes.values()];
+  }
+
+  readonly parameters: Host.AidaClient.FunctionObjectParam<never> = {
+    type: Host.AidaClient.ParametersTypes.OBJECT,
+    description: '',
+    nullable: true,
+    required: [],
+    properties: {},
+  };
+
+  displayInfoFromArgs(): {
+    title: string,
+    action: string,
+  } {
+    return {
+      title: lockedString(UIStringsNotTranslate.listingSources),
+      action: 'listSources()',
+    };
+  }
+
+  async handler(
+      _params: Record<string, never>,
+      context: BaseToolCapability&OriginLockCapability,
+      ): Promise<DataHandlerResult<{files: SourceSummary[]}>> {
+    const origin = context.getEstablishedOrigin();
+    if (origin && isOpaqueOrigin(origin)) {
+      return {
+        error: 'Opaque origin not allowed',
+      };
+    }
+
+    const files = ListSourcesTool.getUISourceCodes().filter(file => {
+      const fileUrl = file.url();
+      const fileOrigin = Common.ParsedURL.ParsedURL.extractOrigin(fileUrl);
+      return !origin || fileOrigin === origin;
+    });
+
+    return {
+      result: {
+        files: files.map(file => ({
+                           id: ListSourcesTool.uiSourceCodeId.get(file) ?? 0,
+                           name: file.fullDisplayName(),
+                         })),
+      },
+    };
+  }
+}