chrome-devtools-frontend 1.0.1643855 → 1.0.1646286

package/front_end/models/ai_assistance/agents/ContextSelectionAgent.ts

@@ -15,6 +15,8 @@ import type * as Trace from '../../trace/trace.js';
 import * as Workspace from '../../workspace/workspace.js';
 import {isOpaqueOrigin} from '../AiOrigins.js';
 import {DOMNodeContext} from '../contexts/DOMNodeContext.js';
+import {FileContext} from '../contexts/FileContext.js';
+import {getRequestContextOrigin, RequestContext} from '../contexts/RequestContext.js';
 import {debugLog} from '../debug.js';
 import {StorageItem} from '../StorageItem.js';
 
@@ -26,8 +28,6 @@ import {
   type ContextResponse,
   type RequestOptions,
 } from './AiAgent.js';
-import {FileContext} from './FileAgent.js';
-import {getRequestContextOrigin, RequestContext} from './NetworkAgent.js';
 import {PerformanceTraceContext} from './PerformanceAgent.js';
 import {StorageContext} from './StorageAgent.js';
 

package/front_end/models/ai_assistance/agents/FileAgent.ts

@@ -5,13 +5,11 @@
 import * as Host from '../../../core/host/host.js';
 import * as Root from '../../../core/root/root.js';
 import type * as Workspace from '../../workspace/workspace.js';
-import {FileFormatter} from '../data_formatters/FileFormatter.js';
 
 import {
   AiAgent,
-  type ContextDetail,
   type ContextResponse,
-  ConversationContext,
+  type ConversationContext,
   type RequestOptions,
   ResponseType,
 } from './AiAgent.js';
@@ -75,31 +73,6 @@ External Resources:
 MDN Web Docs: JavaScript Functions: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Functions
 `;
 
-export class FileContext extends ConversationContext<Workspace.UISourceCode.UISourceCode> {
-  #file: Workspace.UISourceCode.UISourceCode;
-
-  constructor(file: Workspace.UISourceCode.UISourceCode) {
-    super();
-    this.#file = file;
-  }
-
-  override getURL(): string {
-    return this.#file.url();
-  }
-
-  override getItem(): Workspace.UISourceCode.UISourceCode {
-    return this.#file;
-  }
-
-  override getTitle(): string {
-    return this.#file.displayName();
-  }
-
-  override async refresh(): Promise<void> {
-    await this.#file.requestContentData();
-  }
-}
-
 /**
  * One agent instance handles one conversation. Create a new agent
  * instance for a new conversation.
@@ -126,27 +99,21 @@ export class FileAgent extends AiAgent<Workspace.UISourceCode.UISourceCode> {
       return;
     }
 
+    const details = await selectedFile.getUserFacingDetails();
+    if (!details) {
+      return;
+    }
+
     yield {
       type: ResponseType.CONTEXT,
-      details: createContextDetailsForFileAgent(selectedFile),
+      details,
     };
   }
 
   override async enhanceQuery(
       query: string, selectedFile: ConversationContext<Workspace.UISourceCode.UISourceCode>|null): Promise<string> {
-    const fileEnchantmentQuery = selectedFile ?
-        `# Selected file\n${new FileFormatter(selectedFile.getItem()).formatFile()}\n\n# User request\n\n` :
-        '';
+    const promptDetails = selectedFile ? await selectedFile.getPromptDetails() : null;
+    const fileEnchantmentQuery = promptDetails ? `${promptDetails}\n\n# User request\n\n` : '';
     return `${fileEnchantmentQuery}${query}`;
   }
 }
-
-function createContextDetailsForFileAgent(selectedFile: ConversationContext<Workspace.UISourceCode.UISourceCode>):
-    [ContextDetail, ...ContextDetail[]] {
-  return [
-    {
-      title: 'Selected file',
-      text: new FileFormatter(selectedFile.getItem()).formatFile(),
-    },
-  ];
-}

package/front_end/models/ai_assistance/agents/NetworkAgent.snapshot.txt

@@ -10,7 +10,7 @@ Content:
       },
       {
         "title": "Response",
-        "text": "Response headers:\ncontent-type: bar2\nx-forwarded-for: bar3\n\nResponse body:\n{\"request\":\"body\"}\n\nResponse status: 200 \nNetwork request status: pending\n"
+        "text": "Response headers:\ncontent-type: bar2\nx-forwarded-for: bar3\n\nResponse body:\n{\"request\":\"body\"}\n\nResponse status: 200\nNetwork request status: pending\n"
       },
       {
         "title": "Timing",
@@ -59,7 +59,7 @@ Content:
   {
     "parts": [
       {
-        "text": "# Selected network request \nRequest: https://www.example.com\n\nRequest headers:\ncontent-type: bar1\n\nResponse headers:\ncontent-type: bar2\nx-forwarded-for: bar3\n\nResponse body:\n{\"request\":\"body\"}\n\nResponse status: 200 \nNetwork request status: pending\n\nRequest timing:\nQueued at (timestamp): 0 s\nStarted at (timestamp): 501 s\nQueueing (duration): 501 s\nConnection start (stalled) (duration): 800 ms\nRequest sent (duration): 100 ms\nDuration (duration): 501 s\n\nRequest initiator chain:\n- URL: <redacted cross-origin initiator URL>\n\t- URL: https://www.example.com\n\t\t- URL: https://www.example.com/1\n\t\t- URL: https://www.example.com/2\n\n# User request\n\ntest"
+        "text": "# Selected network request\nRequest: https://www.example.com\n\nRequest headers:\ncontent-type: bar1\n\nResponse headers:\ncontent-type: bar2\nx-forwarded-for: bar3\n\nResponse body:\n{\"request\":\"body\"}\n\nResponse status: 200\nNetwork request status: pending\n\nRequest timing:\nQueued at (timestamp): 0 s\nStarted at (timestamp): 501 s\nQueueing (duration): 501 s\nConnection start (stalled) (duration): 800 ms\nRequest sent (duration): 100 ms\nDuration (duration): 501 s\n\nRequest initiator chain:\n- URL: <redacted cross-origin initiator URL>\n\t- URL: https://www.example.com\n\t\t- URL: https://www.example.com/1\n\t\t- URL: https://www.example.com/2\n\n# User request\n\ntest"
       }
     ],
     "role": 1

package/front_end/models/ai_assistance/agents/NetworkAgent.ts

@@ -2,21 +2,14 @@
 // 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 type * as Platform from '../../../core/platform/platform.js';
 import * as Root from '../../../core/root/root.js';
 import type * as SDK from '../../../core/sdk/sdk.js';
-import type * as NetworkTimeCalculator from '../../network_time_calculator/network_time_calculator.js';
-import {extractContextOrigin} from '../AiOrigins.js';
-import {NetworkRequestFormatter} from '../data_formatters/NetworkRequestFormatter.js';
+import type {RequestContext} from '../contexts/RequestContext.js';
 
 import {
   AiAgent,
-  type ContextDetail,
   type ContextResponse,
-  ConversationContext,
   type RequestOptions,
   ResponseType,
 } from './AiAgent.js';
@@ -73,90 +66,6 @@ This request aims to retrieve a list of products matching the search query "lapt
 `;
 /* clang-format on */
 
-/*
-* Strings that don't need to be translated at this time.
-*/
-const UIStringsNotTranslate = {
-  /**
-   * @description Heading text for the block that shows the network request details.
-   */
-  request: 'Request',
-  /**
-   * @description Heading text for the block that shows the network response details.
-   */
-  response: 'Response',
-  /**
-   * @description Prefix text for request URL.
-   */
-  requestUrl: 'Request URL',
-  /**
-   * @description Title text for request timing details.
-   */
-  timing: 'Timing',
-  /**
-   * @description Title text for request initiator chain.
-   */
-  requestInitiatorChain: 'Request initiator chain',
-} as const;
-
-const lockedString = i18n.i18n.lockedString;
-
-/**
- * Returns the origin for a network request in the AI context.
- *
- * To prevent cross-origin prompt injection attacks, HAR-imported requests
- * are isolated from live pages. We assign them a virtual origin
- * (`imported-har://${domain}`) so they do not share the origin of live pages
- * (e.g., `https://${domain}`). This forces a conversation reset when transitioning
- * between imported HAR data and live pages.
- */
-export function getRequestContextOrigin(request: SDK.NetworkRequest.NetworkRequest): string {
-  const origin = extractContextOrigin(request.documentURL);
-  if (request.isImportedHar()) {
-    const parsed = Common.ParsedURL.ParsedURL.fromString(origin as Platform.DevToolsPath.UrlString);
-    return `imported-har://${parsed ? parsed.domain() : origin}`;
-  }
-  return origin;
-}
-
-export class RequestContext extends ConversationContext<SDK.NetworkRequest.NetworkRequest> {
-  #request: SDK.NetworkRequest.NetworkRequest;
-  #calculator: NetworkTimeCalculator.NetworkTransferTimeCalculator;
-
-  constructor(
-      request: SDK.NetworkRequest.NetworkRequest, calculator: NetworkTimeCalculator.NetworkTransferTimeCalculator) {
-    super();
-    this.#request = request;
-    this.#calculator = calculator;
-  }
-
-  /**
-   * Note: this is not the literal origin of the network request. This URL
-   * is used to determine when we should force the user to start a new AI
-   * conversation when the context changes. We allow a single AI conversation to
-   * inspect all network requests that were made for that given target URL.
-   */
-  override getURL(): string {
-    return this.#request.documentURL;
-  }
-
-  override getOrigin(): string {
-    return getRequestContextOrigin(this.#request);
-  }
-
-  override getItem(): SDK.NetworkRequest.NetworkRequest {
-    return this.#request;
-  }
-
-  get calculator(): NetworkTimeCalculator.NetworkTimeCalculator {
-    return this.#calculator;
-  }
-
-  override getTitle(): string {
-    return this.#request.name();
-  }
-}
-
 /**
  * One agent instance handles one conversation. Create a new agent
  * instance for a new conversation.
@@ -183,9 +92,14 @@ export class NetworkAgent extends AiAgent<SDK.NetworkRequest.NetworkRequest> {
       return;
     }
 
+    const details = await selectedNetworkRequest.getUserFacingDetails();
+    if (!details) {
+      return;
+    }
+
     yield {
       type: ResponseType.CONTEXT,
-      details: await createContextDetailsForNetworkAgent(selectedNetworkRequest),
+      details,
       widgets: [{
         name: 'NETWORK_REQUEST_GENERAL_HEADERS',
         data: {
@@ -196,46 +110,8 @@ export class NetworkAgent extends AiAgent<SDK.NetworkRequest.NetworkRequest> {
   }
 
   override async enhanceQuery(query: string, selectedNetworkRequest: RequestContext|null): Promise<string> {
-    const networkEnchantmentQuery = selectedNetworkRequest ?
-        `# Selected network request \n${
-            await (new NetworkRequestFormatter(selectedNetworkRequest.getItem(), selectedNetworkRequest.calculator)
-                       .formatNetworkRequest())}\n\n# User request\n\n` :
-        '';
+    const promptDetails = selectedNetworkRequest ? await selectedNetworkRequest.getPromptDetails() : null;
+    const networkEnchantmentQuery = promptDetails ? `${promptDetails}\n\n# User request\n\n` : '';
     return `${networkEnchantmentQuery}${query}`;
   }
 }
-
-async function createContextDetailsForNetworkAgent(
-    selectedNetworkRequest: RequestContext,
-    ): Promise<[ContextDetail, ...ContextDetail[]]> {
-  const request = selectedNetworkRequest.getItem();
-  const formatter = new NetworkRequestFormatter(request, selectedNetworkRequest.calculator);
-  const requestContextDetail: ContextDetail = {
-    title: lockedString(UIStringsNotTranslate.request),
-    text: lockedString(UIStringsNotTranslate.requestUrl) + ': ' + request.url() + '\n\n' +
-        formatter.formatRequestHeaders(),
-  };
-  const responseBody = await formatter.formatResponseBody();
-  const responseBodyString = responseBody ? `\n\n${responseBody}` : '';
-
-  const responseContextDetail: ContextDetail = {
-    title: lockedString(UIStringsNotTranslate.response),
-    text: formatter.formatResponseHeaders() + responseBodyString +
-        `\n\n${formatter.formatStatus()}${formatter.formatFailureReasons()}`,
-  };
-  const timingContextDetail: ContextDetail = {
-    title: lockedString(UIStringsNotTranslate.timing),
-    text: formatter.formatNetworkRequestTiming(),
-  };
-  const initiatorChainContextDetail: ContextDetail = {
-    title: lockedString(UIStringsNotTranslate.requestInitiatorChain),
-    text: formatter.formatRequestInitiatorChain(),
-  };
-
-  return [
-    requestContextDetail,
-    responseContextDetail,
-    timingContextDetail,
-    initiatorChainContextDetail,
-  ];
-}

package/front_end/models/ai_assistance/agents/PerformanceAgent.ts

@@ -15,7 +15,7 @@ import * as Logs from '../../logs/logs.js';
 import * as SourceMapScopes from '../../source_map_scopes/source_map_scopes.js';
 import * as TextUtils from '../../text_utils/text_utils.js';
 import * as Trace from '../../trace/trace.js';
-import {extractContextOrigin} from '../AiOrigins.js';
+import {canResourceContentsBeReadForTrace, extractContextOrigin} from '../AiOrigins.js';
 import {sanitizeHeaders} from '../data_formatters/NetworkRequestFormatter.js';
 import {
   PerformanceInsightFormatter,
@@ -751,11 +751,26 @@ export class PerformanceAgent extends AiAgent<AgentFocus> {
     yield* super.run(initialQuery, options);
   }
 
+  /**
+   * Clears performance-agent-specific caches and state.
+   * This is called when the conversation needs to be reset (e.g. on navigation)
+   * to prevent stale formatters, trace facts, or selection contexts from leaking
+   * into subsequent runs.
+   */
   override clearCache(): void {
+    super.clearCache();
     // Clear the function call cache to prevent stashed tool execution results
     // (which might contain cross-origin resource content fetched before navigation
     // was detected) from being replayed as facts in subsequent runs.
     this.#functionCallCacheForFocus.clear();
+    // Reset the formatter and trace facts so they are recreated with the
+    // correct target and origin on the next execution.
+    this.#formatter = null;
+    this.#traceFacts = [];
+    this.#lastEventForEnhancedQuery = undefined;
+    this.#lastInsightForEnhancedQuery = undefined;
+    this.#additionalSelectionsForDisclosure = [];
+    this.#callTreeContextSet = new WeakSet();
   }
 
   #createFactForTraceSummary(): void {
@@ -1457,8 +1472,16 @@ export class PerformanceAgent extends AiAgent<AgentFocus> {
       },
       handler: async args => {
         debugLog('Function call: getResourceContent');
+        if (!isFresh) {
+          return {error: 'Cannot use this tool on an imported file.'};
+        }
+
+        const url = args.url;
+        const allowedOrigin = context.getOrigin();
+        if (!canResourceContentsBeReadForTrace(url, allowedOrigin)) {
+          return {error: 'Resource not found'};
+        }
 
-        const url = args.url as Platform.DevToolsPath.UrlString;
         let content: string|undefined;
 
         // First check parsedTrace.data.Scripts.

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

@@ -2,6 +2,42 @@
 
 This directory contains the implementations of various AI agents used in the AI Assistance panel in Chrome DevTools.
 
+## Agent Lifecycle & State Management
+
+AI Agents can maintain internal stateful variables to optimize performance or store context (e.g., stashed tool results, formatters, or instruction flags). However, this state must be carefully managed to prevent security leaks (such as cross-origin data leaks after page navigation) or stale results.
+
+### Cache Clearing (`clearCache()`)
+
+The `AiAgent` base class defines a `clearCache()` method. This method is automatically invoked by the system when:
+- An execution error occurs.
+- The user aborts the execution.
+- A cross-origin navigation is detected (via the top-level origin blocking mechanism).
+
+#### Overriding `clearCache()` in Subclasses
+
+If you introduce new stateful member variables in an `AiAgent` subclass, you **must** override `clearCache()` to reset them:
+
+1. Always call `super.clearCache()` to ensure base class cleanup is executed.
+2. Reset any subclass-specific state (e.g., setting formatters to `null`, clearing lists, resetting boolean flags).
+
+Example from `PerformanceAgent`:
+```typescript
+  override clearCache(): void {
+    super.clearCache();
+    this.#functionCallCacheForFocus.clear();
+    this.#formatter = null;
+    this.#traceFacts = [];
+    // ... reset other stateful fields
+  }
+```
+
+### Origin Validation (`isOriginAllowed`)
+
+Before running an execution loop, the system validates the context's origin:
+*   **Opaque Origin Rejection**: Opaque origins are rejected immediately, blocking conversations on untrusted/opaque contexts (like `about:blank`, `data:` URLs, or opaque blob URLs).
+*   **Origin Lock Integrity**: If the conversation is already locked to an origin, the new context's origin must be equivalent (as defined by `areOriginsEquivalent()`) to the locked origin.
+*   **Safety Termination**: If validation fails, a cross-origin error is yielded and execution stops.
+
 ## Performance Agent
 
 The `PerformanceAgent` analyzes performance traces. This documentation details the specific data provided to the agent and the data it can retrieve via functions.
@@ -70,3 +106,31 @@ The agent can request additional data by calling functions. Here is the data the
 #### `selectEventByKey`
 - **Arguments**: `eventKey` (string)
 - **Data Returned to Agent**: Confirmation of success or an error message. (Note: This function also modifies the DevTools UI by selecting the event in the flamechart).
+
+## Styling Agent
+
+The `StylingAgent` assists with CSS styling and layout questions. It can interact with the page to inspect styles, execute Javascript, and optionally emulate devices or vision deficiencies.
+
+### Initial Data Provided to the Agent
+
+The agent is initialized with the selected DOM node context.
+
+### Data Retrieval & Action Functions (Tools)
+
+The agent can call the following functions to retrieve more details or perform actions:
+
+#### `getStyles`
+- **Arguments**: None (it uses the currently selected DOM node).
+- **Data Returned to Agent**: Computed styles and authored styles (matching rules, active stylesheets, etc.) for the selected node.
+
+#### `executeJavaScript`
+- **Arguments**: `query` (string)
+- **Data Returned to Agent**: The result of executing the JavaScript query in the context of the page.
+
+#### `addElementAnnotation`
+- **Arguments**: `elementId` (string), `annotationMessage` (string)
+- **Data Returned to Agent**: Confirmation of success or an error message. (Note: This function also modifies the DevTools UI by adding a visual annotation to the node).
+
+#### `activateDeviceEmulation`
+- **Arguments**: `deviceName` (string), `visionDeficiency` (string, optional)
+- **Data Returned to Agent**: Confirmation of success or an error message. (Note: This function modifies the DevTools UI by enabling device and/or vision deficiency emulation).

package/front_end/models/ai_assistance/agents/StylingAgent.ts

@@ -191,9 +191,18 @@ export class StylingAgent extends AiAgent<SDK.DOMModel.DOMNode> {
       description: getStylesTool.description,
       parameters: getStylesTool.parameters,
       displayInfoFromArgs: getStylesTool.displayInfoFromArgs,
-      handler: args => getStylesTool.handler(args, {
-        conversationContext: this.context ?? null,
-      }),
+      handler: async args => {
+        const context = this.context;
+        if (!context) {
+          return {error: 'Error: Could not find the currently selected element.'};
+        }
+        return await getStylesTool.handler(args, {
+          conversationContext: context,
+          getTarget: () =>
+              SDK.TargetManager.TargetManager.instance().primaryPageTarget() ?? context.getItem().domModel().target(),
+          getEstablishedOrigin: () => context.getOrigin(),
+        });
+      },
     });
 
     const executeJsTool = ToolRegistry.get(ToolName.EXECUTE_JAVASCRIPT);
@@ -281,6 +290,20 @@ export class StylingAgent extends AiAgent<SDK.DOMModel.DOMNode> {
     });
   }
 
+  /**
+   * Clears styling-agent-specific caches and state.
+   * Resets cached emulation data (screenshots, accessibility tree) and the
+   * instructions flag to ensure they are re-evaluated in subsequent queries.
+   */
+  override clearCache(): void {
+    super.clearCache();
+    // Reset emulation state so that subsequent queries will re-initialize
+    // emulation details and fetch fresh data.
+    this.#greenDevEmulationScreenshot = null;
+    this.#greenDevEmulationAxTree = null;
+    this.#hasAddedEmulationInstructions = false;
+  }
+
   override preambleFeatures(): string[] {
     return ['function_calling'];
   }

package/front_end/models/ai_assistance/ai_assistance.ts

@@ -23,6 +23,8 @@ import * as AiUtils from './AiUtils.js';
 import * as BuiltInAi from './BuiltInAi.js';
 import * as ChangeManager from './ChangeManager.js';
 import * as DOMNodeContext from './contexts/DOMNodeContext.js';
+import * as FileContext from './contexts/FileContext.js';
+import * as RequestContext from './contexts/RequestContext.js';
 import * as ConversationSummary from './ConversationSummary.js';
 import * as FileFormatter from './data_formatters/FileFormatter.js';
 import * as LighthouseFormatter from './data_formatters/LighthouseFormatter.js';
@@ -66,6 +68,7 @@ export {
   ExecuteJavaScript,
   ExtensionScope,
   FileAgent,
+  FileContext,
   FileFormatter,
   GetStyles,
   GreenDevAgent,
@@ -80,6 +83,7 @@ export {
   PerformanceAnnotations,
   PerformanceInsightFormatter,
   PerformanceTraceFormatter,
+  RequestContext,
   StorageAgent,
   StorageItem,
   StylingAgent,

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

@@ -0,0 +1,45 @@
+// 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 type * as Workspace from '../../workspace/workspace.js';
+import {type ContextDetail, ConversationContext} from '../agents/AiAgent.js';
+import {FileFormatter} from '../data_formatters/FileFormatter.js';
+
+export class FileContext extends ConversationContext<Workspace.UISourceCode.UISourceCode> {
+  #file: Workspace.UISourceCode.UISourceCode;
+
+  constructor(file: Workspace.UISourceCode.UISourceCode) {
+    super();
+    this.#file = file;
+  }
+
+  override getURL(): string {
+    return this.#file.url();
+  }
+
+  override getItem(): Workspace.UISourceCode.UISourceCode {
+    return this.#file;
+  }
+
+  override getTitle(): string {
+    return this.#file.displayName();
+  }
+
+  override async getPromptDetails(): Promise<string|null> {
+    return `# Selected file\n${new FileFormatter(this.#file).formatFile()}`;
+  }
+
+  override async getUserFacingDetails(): Promise<[ContextDetail, ...ContextDetail[]]|null> {
+    return [
+      {
+        title: 'Selected file',
+        text: new FileFormatter(this.#file).formatFile(),
+      },
+    ];
+  }
+
+  override async refresh(): Promise<void> {
+    await this.#file.requestContentData();
+  }
+}

package/front_end/models/ai_assistance/contexts/RequestContext.snapshot.txt

@@ -0,0 +1,48 @@
+Title: RequestContext getPromptDetails describes the network request correctly
+Content:
+# Selected network request
+Request: https://www.example.com/api/users
+
+Request headers:
+Accept: application/json
+
+Response headers:
+Content-Type: application/json
+
+Response body:
+{}
+
+Response status: 200
+Network request status: pending
+
+Request timing:
+Queued at (timestamp): 0 s
+Started at (timestamp): 0 s
+Connection start (stalled) (duration): -
+Duration (duration): -
+
+Request initiator chain:
+- URL: https://www.example.com/api/users
+=== end content
+
+Title: RequestContext getUserFacingDetails returns details correctly
+Content:
+[
+  {
+    "title": "Request",
+    "text": "Request URL: https://www.example.com/api/users\n\nRequest headers:\nAccept: application/json"
+  },
+  {
+    "title": "Response",
+    "text": "Response headers:\nContent-Type: application/json\n\nResponse body:\n{}\n\nResponse status: 200\nNetwork request status: pending\n"
+  },
+  {
+    "title": "Timing",
+    "text": "Queued at (timestamp): 0 s\nStarted at (timestamp): 0 s\nConnection start (stalled) (duration): -\nDuration (duration): -"
+  },
+  {
+    "title": "Request initiator chain",
+    "text": "- URL: https://www.example.com/api/users"
+  }
+]
+=== end content