chrome-devtools-frontend 1.0.1696961 → 1.0.1697998

package/front_end/models/ai_assistance/AiConversation.ts

@@ -38,7 +38,7 @@ import {FileContext} from './contexts/FileContext.js';
 import {PerformanceTraceContext} from './contexts/PerformanceTraceContext.js';
 import {RequestContext} from './contexts/RequestContext.js';
 import {StorageContext} from './contexts/StorageContext.js';
-import {ToolAnnotation} from './tools/Tool.js';
+import {type OriginLockState, ToolAnnotation} from './tools/Tool.js';
 import {ToolRegistry} from './tools/ToolRegistry.js';
 
 export const NOT_FOUND_IMAGE_DATA = '';
@@ -381,7 +381,7 @@ export class AiConversation {
     const isTransitioningFromStorage = previousType === ConversationType.STORAGE && type !== ConversationType.STORAGE;
     const history = isTransitioningFromStorage ? [] : this.#filterHistoryForNewAgent();
 
-    const options = {
+    const baseOptions = {
       aidaClient: this.#aidaClient,
       serverSideLoggingAllowed: isAiAssistanceServerSideLoggingAllowed(),
       sessionId: this.id,
@@ -390,13 +390,18 @@ export class AiConversation {
       onInspectElement: this.#onInspectElement,
       networkTimeCalculator: this.#networkTimeCalculator,
       lighthouseRecording: this.#lighthouseRecording,
-      allowedOrigin: this.allowedOrigin,
       history,
       targetManager: this.#targetManager,
     };
 
-    this.#agent = Root.Runtime.hostConfig.devToolsAiV2Architecture?.enabled ? new AiAgent2(options) :
-                                                                              this.#createV1Agent(type, options);
+    this.#agent = Root.Runtime.hostConfig.devToolsAiV2Architecture?.enabled ? new AiAgent2({
+      ...baseOptions,
+      originLock: this.getOriginLock,
+    }) :
+                                                                              this.#createV1Agent(type, {
+                                                                                ...baseOptions,
+                                                                                allowedOrigin: this.allowedOrigin,
+                                                                              });
   }
 
   #createV1Agent(type: ConversationType, options: AgentOptions): AiAgent<unknown> {
@@ -553,19 +558,40 @@ export class AiConversation {
   }
 
   /**
-   * Returns the permitted origin for agent tool execution, or blocks execution
-   * if an unapproved cross-origin navigation occurred during the current run.
+   * Returns the conversation's origin-locking state:
+   * - `BLOCKED_BY_NAVIGATION`: An unapproved cross-origin navigation occurred during the active run.
+   * - `ESTABLISHED_ORIGIN`: The conversation is locked to the established origin.
+   * - `UNINITIALIZED`: No origin lock has been established yet.
    */
-  allowedOrigin = (): AllowedOriginResult => {
+  getOriginLock = (): OriginLockState => {
     if (this.#navigationOccurredDuringRun) {
-      return {blocked: true};
+      return {status: 'BLOCKED_BY_NAVIGATION'};
     }
     if (this.#origin) {
-      return {origin: this.#origin};
+      return {status: 'ESTABLISHED_ORIGIN', origin: this.#origin};
+    }
+    const pageOrigin = getPrimaryPageSecurityOrigin(this.#targetManager);
+    if (pageOrigin) {
+      this.#origin = pageOrigin;
+      return {status: 'ESTABLISHED_ORIGIN', origin: this.#origin};
     }
-    this.#origin = getPrimaryPageSecurityOrigin(this.#targetManager);
 
-    return {origin: this.#origin};
+    return {status: 'UNINITIALIZED'};
+  };
+
+  /**
+   * Returns the permitted origin for legacy V1 agent tool execution.
+   * Maps the OriginLockState to the AllowedOriginResult format expected by V1 agents.
+   */
+  allowedOrigin = (): AllowedOriginResult => {
+    const lock = this.getOriginLock();
+    if (lock.status === 'BLOCKED_BY_NAVIGATION') {
+      return {blocked: true};
+    }
+    if (lock.status === 'ESTABLISHED_ORIGIN') {
+      return {origin: lock.origin};
+    }
+    return {origin: undefined};
   };
 }
 

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

@@ -11,7 +11,10 @@ import {ChangeManager} from '../ChangeManager.js';
 import {LighthouseFormatter} from '../data_formatters/LighthouseFormatter.js';
 import {debugLog} from '../debug.js';
 import {ExtensionScope} from '../ExtensionScope.js';
-import {ToolName} from '../tools/Tool.js';
+import {
+  type OriginLockState,
+  ToolName,
+} from '../tools/Tool.js';
 import {ToolRegistry} from '../tools/ToolRegistry.js';
 
 import {
@@ -253,7 +256,11 @@ export class AccessibilityAgent extends AiAgent<LHModel.ReporterTypes.ReportJSON
               createExtensionScope: this.#createExtensionScope.bind(this),
               execJs: this.#execJs,
               getExecutionContextNode: () => this.#getDocumentBodyNode(),
-              getEstablishedOrigin: () => this.context?.getOrigin(),
+              getOriginLock: (): OriginLockState => {
+                // V1 AccessibilityAgent adapts the selected node's security origin to OriginLockState.
+                const origin = this.context?.getOrigin();
+                return origin ? {status: 'ESTABLISHED_ORIGIN', origin} : {status: 'UNINITIALIZED'};
+              },
             },
             options,
         );

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

@@ -20,6 +20,7 @@ import {StorageContext} from '../contexts/StorageContext.js';
 import {formatBytesToKb, seconds} from '../data_formatters/UnitFormatters.js';
 import {debugLog} from '../debug.js';
 import {StorageItem} from '../StorageItem.js';
+import {isOriginAllowedByLock} from '../tools/Tool.js';
 
 import {
   type AgentOptions,
@@ -587,4 +588,29 @@ export class ContextSelectionAgent extends AiAgent<never> {
 
     return [...uiSourceCodes.values()];
   }
+
+  /**
+   * Resolves a workspace source file by its ID, ensuring that the file's security
+   * origin is authorized by the conversation's established origin lock.
+   *
+   * Fails closed by returning `undefined` if the established origin is missing or opaque,
+   * if the file ID is invalid, or if the file origin does not match the lock.
+   */
+  static getSourceById(
+      id: number,
+      establishedOrigin?: SDK.SecurityOrigin.SecurityOrigin,
+      // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
+      workspace: Workspace.Workspace.WorkspaceImpl = Workspace.Workspace.WorkspaceImpl.instance(),
+      ): Workspace.UISourceCode.UISourceCode|undefined {
+    if (!establishedOrigin || !Number.isInteger(id) || id <= 0) {
+      return undefined;
+    }
+    return ContextSelectionAgent.getUISourceCodes(workspace).find(file => {
+      if (ContextSelectionAgent.uiSourceCodeId.get(file) !== id) {
+        return false;
+      }
+      return isOriginAllowedByLock({status: 'ESTABLISHED_ORIGIN', origin: establishedOrigin},
+                                   FileContext.originForUISourceCode(file));
+    });
+  }
 }

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

@@ -8,7 +8,10 @@ import type * as SDK from '../../../core/sdk/sdk.js';
 import {ChangeManager} from '../ChangeManager.js';
 import {ExtensionScope} from '../ExtensionScope.js';
 import {AI_ASSISTANCE_CSS_CLASS_NAME} from '../injected.js';
-import {ToolName} from '../tools/Tool.js';
+import {
+  type OriginLockState,
+  ToolName,
+} from '../tools/Tool.js';
 import {ToolRegistry} from '../tools/ToolRegistry.js';
 
 import {
@@ -154,8 +157,10 @@ export class StylingAgent extends AiAgent<SDK.DOMModel.DOMNode> {
         }
         return await getStylesTool.handler(args, {
           getTarget: () => this.targetManager.primaryPageTarget() ?? context.getItem().domModel().target(),
-          getEstablishedOrigin: () => {
-            return context.getOrigin();
+          getOriginLock: (): OriginLockState => {
+            // V1 StylingAgent adapts the selected DOM node's security origin to OriginLockState.
+            const origin = context.getOrigin();
+            return origin ? {status: 'ESTABLISHED_ORIGIN', origin} : {status: 'UNINITIALIZED'};
           },
         });
       },
@@ -176,7 +181,11 @@ export class StylingAgent extends AiAgent<SDK.DOMModel.DOMNode> {
             createExtensionScope: this.#createExtensionScope.bind(this),
             execJs: this.#execJs,
             getExecutionContextNode: () => this.context?.getItem() ?? null,
-            getEstablishedOrigin: () => this.context?.getOrigin(),
+            getOriginLock: (): OriginLockState => {
+              // V1 StylingAgent adapts the selected DOM node's security origin to OriginLockState.
+              const origin = this.context?.getOrigin();
+              return origin ? {status: 'ESTABLISHED_ORIGIN', origin} : {status: 'UNINITIALIZED'};
+            },
           },
           options,
           ),

package/front_end/models/ai_assistance/ai_assistance.ts

@@ -46,18 +46,18 @@ import * as ExecuteJavaScript from './tools/ExecuteJavaScript.js';
 import * as GetCookieValues from './tools/GetCookieValues.js';
 import * as GetDetailedCallTree from './tools/GetDetailedCallTree.js';
 import * as GetElementAccessibilityDetails from './tools/GetElementAccessibilityDetails.js';
-import * as GetFunctionCode from './tools/GetFunctionCode.js';
 import * as GetInsightDetails from './tools/GetInsightDetails.js';
 import * as GetLighthouseAudits from './tools/GetLighthouseAudits.js';
 import * as GetNetworkRequestDetails from './tools/GetNetworkRequestDetails.js';
-import * as GetResourceContent from './tools/GetResourceContent.js';
 import * as GetSourceContent from './tools/GetSourceContent.js';
 import * as GetStorageBreakdown from './tools/GetStorageBreakdown.js';
 import * as GetStorageValues from './tools/GetStorageValues.js';
 import * as GetStyles from './tools/GetStyles.js';
 import * as GetTraceEventByKey from './tools/GetTraceEventByKey.js';
+import * as GetTraceFunctionCode from './tools/GetTraceFunctionCode.js';
 import * as GetTraceMainThreadSummary from './tools/GetTraceMainThreadSummary.js';
 import * as GetTraceNetworkSummary from './tools/GetTraceNetworkSummary.js';
+import * as GetTraceResourceContent from './tools/GetTraceResourceContent.js';
 import * as ListCookies from './tools/ListCookies.js';
 import * as ListNetworkRequests from './tools/ListNetworkRequests.js';
 import * as ListPageOrigins from './tools/ListPageOrigins.js';
@@ -99,18 +99,18 @@ export {
   GetCookieValues,
   GetDetailedCallTree,
   GetElementAccessibilityDetails,
-  GetFunctionCode,
   GetInsightDetails,
   GetLighthouseAudits,
   GetNetworkRequestDetails,
-  GetResourceContent,
   GetSourceContent,
   GetStorageBreakdown,
   GetStorageValues,
   GetStyles,
   GetTraceEventByKey,
+  GetTraceFunctionCode,
   GetTraceMainThreadSummary,
   GetTraceNetworkSummary,
+  GetTraceResourceContent,
   Injected,
   LighthouseFormatter,
   ListCookies,

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

@@ -8,8 +8,8 @@ allowed-tools:
   - getTraceMainThreadSummary
   - getTraceNetworkSummary
   - getDetailedCallTree
-  - getFunctionCode
-  - getResourceContent
+  - getTraceFunctionCode
+  - getTraceResourceContent
   - getInsightDetails
 ---
 You are an expert web performance assistant integrated into Chrome DevTools.
@@ -29,7 +29,8 @@ Your goal is to provide actionable advice about web page performance by analyzin
 3. **Call Tree, Event & Source Inspection**:
    - Use `getDetailedCallTree` to retrieve bottom-up execution trees for expensive main thread tasks.
    - Use `getTraceEventByKey` to inspect timing and payload data for individual events.
-   - Use `getFunctionCode` or `getResourceContent` to inspect the source code and identify root causes.
+   - Use `getTraceFunctionCode` to inspect a specific function identified in the call tree, including line-by-line CPU profile execution costs.
+   - Use `getTraceResourceContent` to inspect the full text of a script or resource captured within the trace by URL.
 
 4. **UI Selection & Trace Recording**:
    - Use `selectTraceEventByKey` to reveal and select an event in the Performance Flamechart if requested.

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

@@ -6,7 +6,7 @@ import * as SDK from '../../../core/sdk/sdk.js';
 import type * as Protocol from '../../../generated/protocol.js';
 
 import {MAX_TARGET_ORIGINS} from './DOMStorageUtils.js';
-import type {OriginLockCapability} from './Tool.js';
+import {isOriginAllowedByLock, type OriginLockCapability, resolveOriginFromLock} from './Tool.js';
 
 export interface CookieDetails {
   name: string;
@@ -25,14 +25,14 @@ export interface CookieDetails {
 }
 
 /**
- * Resolves and validates target origins against the established context origin and primary page target.
+ * Resolves and validates target origins against the conversation's origin lock state and primary page target.
  *
  * When `requestedOrigins` is empty or omitted, defaults to the established context origin.
  * Rejects opaque origins, mismatches with the primary page origin, and cross-origin targets.
  * Limits results to at most `MAX_TARGET_ORIGINS` unique origins.
  *
  * @param requestedOrigins Optional list of origin URLs to validate.
- * @param context The origin lock capability containing the established origin.
+ * @param context The origin lock capability providing access to the conversation's origin lock state.
  * @param targetManager The target manager used to resolve the primary page target.
  * @returns An object with validated target origins and the primary page target, or an error object.
  */
@@ -44,10 +44,12 @@ export function resolveAllowedTargetOrigins(
   error: string,
 }
 {
-  const establishedOrigin = context.getEstablishedOrigin();
-  if (!establishedOrigin || establishedOrigin.isOpaque()) {
-    return {error: 'No origin available or not allowed.'};
+  const originLock = context.getOriginLock();
+  const originResult = resolveOriginFromLock(originLock);
+  if ('error' in originResult) {
+    return originResult;
   }
+  const establishedOrigin = originResult.origin;
 
   const primaryPageTarget = targetManager.primaryPageTarget();
   if (!primaryPageTarget) {
@@ -55,7 +57,7 @@ export function resolveAllowedTargetOrigins(
   }
 
   const pageOrigin = primaryPageTarget.inspectedSecurityOrigin();
-  if (!pageOrigin.isSameOriginWith(establishedOrigin)) {
+  if (!isOriginAllowedByLock(originLock, pageOrigin)) {
     return {error: 'Page origin does not match allowed origin.'};
   }
 
@@ -65,7 +67,7 @@ export function resolveAllowedTargetOrigins(
       [establishedOrigin];
 
   const validOrigins =
-      candidateOrigins.filter(origin => origin.isSameOriginWith(establishedOrigin)).map(origin => origin.siteId());
+      candidateOrigins.filter(origin => isOriginAllowedByLock(originLock, origin)).map(origin => origin.siteId());
 
   const targetOrigins = Array.from(new Set(validOrigins)).slice(0, MAX_TARGET_ORIGINS);
   if (targetOrigins.length === 0) {

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

@@ -131,7 +131,7 @@ const data = {
       return {error: 'Error: Could not find the context node for execution.'};
     }
 
-    if (!isOriginAllowedByLock(context.getEstablishedOrigin(), executionNode.securityOrigin())) {
+    if (!isOriginAllowedByLock(context.getOriginLock(), executionNode.securityOrigin())) {
       return {error: 'Error: Cannot execute JavaScript on cross-origin target.'};
     }
 

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

@@ -80,8 +80,6 @@ export class GetElementAccessibilityDetailsTool implements
       params: GetElementAccessibilityDetailsArgs,
       context: BaseToolCapability&TargetCapability&OriginLockCapability,
       ): Promise<DataHandlerResult<string>> {
-    const establishedOrigin = context.getEstablishedOrigin();
-
     const target = context.getTarget();
     if (!target) {
       return {error: 'Error: Inspected target not found.'};
@@ -99,7 +97,7 @@ export class GetElementAccessibilityDetailsTool implements
     // Security check: Ensure the element matches the active conversation's origin lock.
     // Because getTarget() returns the primary page target to support resolving elements
     // across frames, origin validation must be enforced directly on the resolved node.
-    if (!isOriginAllowedByLock(establishedOrigin, resolved.securityOrigin())) {
+    if (!isOriginAllowedByLock(context.getOriginLock(), resolved.securityOrigin())) {
       return {error: 'Error: Node does not belong to the current origin.'};
     }
 

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

@@ -14,6 +14,7 @@ import {
   type DataTool,
   isOriginAllowedByLock,
   type OriginLockCapability,
+  resolveOriginFromLock,
   type ToolArgs,
   ToolName,
 } from './Tool.js';
@@ -75,9 +76,12 @@ export class GetNetworkRequestDetailsTool implements
       args: GetNetworkRequestDetailsArgs,
       context: BaseToolCapability&OriginLockCapability,
       ): Promise<DataHandlerResult<unknown>> {
-    // A conversation is locked to an origin once the first query is made.
-    // We only allow inspecting requests matching the conversation's established origin.
-    const establishedOrigin = context.getEstablishedOrigin();
+    const originLock = context.getOriginLock();
+    const originResult = resolveOriginFromLock(originLock);
+    if ('error' in originResult) {
+      return originResult;
+    }
+    const establishedOrigin = originResult.origin;
 
     // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     const networkLog = this.#networkLog ?? Logs.NetworkLog.NetworkLog.instance();
@@ -87,13 +91,10 @@ export class GetNetworkRequestDetailsTool implements
       }
 
       // If the conversation is locked to an origin, only allow accessing requests from that origin.
-      return isOriginAllowedByLock(establishedOrigin, req.initiatorSecurityOrigin());
+      return isOriginAllowedByLock(originLock, req.initiatorSecurityOrigin());
     });
 
-    // If establishedOrigin is undefined or opaque, isOriginAllowedByLock() fails closed,
-    // so find() will never return a request. We check establishedOrigin here as a defensive
-    // guard and to narrow the type for NetworkRequestFormatter below.
-    if (!establishedOrigin || !request) {
+    if (!request) {
       return {
         error: 'No request found',
       };

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

@@ -13,6 +13,7 @@ import {
   type DataHandlerResult,
   type DataTool,
   type OriginLockCapability,
+  resolveOriginFromLock,
   type ToolArgs,
   ToolName,
 } from './Tool.js';
@@ -64,14 +65,12 @@ export class GetSourceContentTool implements
       args: GetSourceContentArgs,
       context: BaseToolCapability&OriginLockCapability,
       ): Promise<DataHandlerResult<{content: string}>> {
-    const establishedOrigin = context.getEstablishedOrigin();
-    if (!establishedOrigin) {
-      return {
-        error: 'Unable to find file.',
-      };
+    const originResult = resolveOriginFromLock(context.getOriginLock());
+    if ('error' in originResult) {
+      return originResult;
     }
 
-    const file = ListSourcesTool.getSourceById(args.id, establishedOrigin);
+    const file = ListSourcesTool.getSourceById(args.id, originResult.origin);
 
     if (!file) {
       return {

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

@@ -8,7 +8,8 @@ import * as Platform from '../../../core/platform/platform.js';
 import * as SDK from '../../../core/sdk/sdk.js';
 import type {FunctionHandlerOptions} from '../agents/AiAgent.js';
 
-import {MAX_TARGET_ORIGINS, resolveDOMStorages} from './DOMStorageUtils.js';
+import {resolveAllowedTargetOrigins} from './CookieUtils.js';
+import {resolveDOMStorages} from './DOMStorageUtils.js';
 import {
   type BaseToolCapability,
   type DataHandlerResult,
@@ -112,31 +113,11 @@ export class GetStorageValuesTool implements DataTool<GetStorageValuesArgs, GetS
 
     // eslint-disable-next-line @devtools/no-instance-of-migrated-singletons
     const targetManager = SDK.TargetManager.TargetManager.instance();
-    const primaryPageTarget = targetManager.primaryPageTarget();
-
-    const establishedOrigin = context.getEstablishedOrigin();
-    if (!establishedOrigin || establishedOrigin.isOpaque()) {
-      return {error: 'No origin available or not allowed.'};
-    }
-
-    if (!primaryPageTarget) {
-      return {error: 'No origin available or not allowed.'};
-    }
-
-    const pageOrigin = primaryPageTarget.inspectedSecurityOrigin();
-    if (!pageOrigin.isSameOriginWith(establishedOrigin)) {
-      return {error: 'No origin available or not allowed.'};
-    }
-
-    const candidateOrigins: SDK.SecurityOrigin.SecurityOrigin[] = (args.origins && args.origins.length > 0) ?
-        args.origins.map(origin => SDK.SecurityOrigin.SecurityOrigin.create(origin)) :
-        [establishedOrigin];
-    const validOrigins =
-        candidateOrigins.filter(origin => origin.isSameOriginWith(establishedOrigin)).map(origin => origin.siteId());
-    const targetOrigins = Array.from(new Set(validOrigins)).slice(0, MAX_TARGET_ORIGINS);
-    if (targetOrigins.length === 0) {
-      return {error: 'No valid origins found.'};
+    const targetOriginsResult = resolveAllowedTargetOrigins(args.origins, context, targetManager);
+    if ('error' in targetOriginsResult) {
+      return {error: targetOriginsResult.error};
     }
+    const {targetOrigins, primaryPageTarget} = targetOriginsResult;
 
     const storageKey = (targetOrigins.length === 1 && args.storageKey) ? args.storageKey : undefined;
 

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

@@ -97,8 +97,6 @@ export class GetStylesTool implements
       return {error: 'Error: Could not find the inspected page.'};
     }
 
-    const establishedOrigin = context.getEstablishedOrigin();
-
     for (const uid of params.elements) {
       result[uid] = {computed: {}, authored: {}};
       const node = new SDK.DOMModel.DeferredDOMNode(target, uid as Protocol.DOM.BackendNodeId);
@@ -109,7 +107,7 @@ export class GetStylesTool implements
       // Security check: Ensure the resolved element belongs to the locked origin.
       // Because getTarget() returns the primary page target to support resolving elements
       // across frames, origin validation must be enforced directly on the resolved node.
-      if (!isOriginAllowedByLock(establishedOrigin, resolved.securityOrigin())) {
+      if (!isOriginAllowedByLock(context.getOriginLock(), resolved.securityOrigin())) {
         return {error: 'Error: Node does not belong to the current origin.'};
       }
       const styles = await resolved.domModel().cssModel().getComputedStyle(resolved.id);

package/front_end/models/ai_assistance/tools/{GetFunctionCode.ts → GetTraceFunctionCode.ts}

@@ -21,54 +21,67 @@ const UIStringsNotTranslate = {
 
 const lockedString = i18n.i18n.lockedString;
 
-export interface GetFunctionCodeArgs extends ToolArgs {
+/**
+ * Arguments for {@link GetTraceFunctionCodeTool}.
+ */
+export interface GetTraceFunctionCodeArgs extends ToolArgs {
+  /** The URL of the script containing the function recorded in the performance trace. */
   scriptUrl: string;
+  /** The line number where the function is defined (0-based, as reported in the call tree). */
   line: number;
+  /** The column number where the function is defined (0-based, as reported in the call tree). */
   column: number;
 }
 
-export class GetFunctionCodeTool implements
-    DataTool<GetFunctionCodeArgs, string, BaseToolCapability&PerformanceTraceCapability> {
-  readonly name: ToolName = ToolName.GET_FUNCTION_CODE;
+/**
+ * Retrieves function code and line-by-line CPU profile execution costs from the performance trace.
+ *
+ * Preconditions:
+ * - Requires an active, freshly recorded trace session (fails on imported traces).
+ * - Requires resource access via the performance trace context.
+ */
+export class GetTraceFunctionCodeTool implements
+    DataTool<GetTraceFunctionCodeArgs, string, BaseToolCapability&PerformanceTraceCapability> {
+  readonly name: ToolName = ToolName.GET_TRACE_FUNCTION_CODE;
   readonly description: string =
-      'Retrieves the code for a function defined at the given location. The result is annotated with the runtime performance of each line of code.';
+      'Retrieves the code for a function recorded in the performance trace at the specified location, annotated with line-by-line CPU runtime profiling execution costs. Do not call this tool unless a performance trace recording is actively loaded.';
 
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetFunctionCodeArgs> = {
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceFunctionCodeArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,
-    description: 'Arguments for looking up function code.',
+    description: 'Arguments for looking up function code from the performance trace profile.',
     nullable: false,
     properties: {
       scriptUrl: {
         type: Host.AidaClient.ParametersTypes.STRING,
-        description: 'The url of the function.',
+        description: 'The URL of the script containing the function recorded in the performance trace.',
         nullable: false,
       },
       line: {
         type: Host.AidaClient.ParametersTypes.INTEGER,
-        description: 'The line number where the function is defined.',
+        description: 'The line number where the function is defined (0-based, as reported in the call tree).',
         nullable: false,
       },
       column: {
         type: Host.AidaClient.ParametersTypes.INTEGER,
-        description: 'The column number where the function is defined.',
+        description: 'The column number where the function is defined (0-based, as reported in the call tree).',
         nullable: false,
       },
     },
     required: ['scriptUrl', 'line', 'column'],
   };
 
-  displayInfoFromArgs(params: GetFunctionCodeArgs): {
+  displayInfoFromArgs(params: GetTraceFunctionCodeArgs): {
     title: string,
     action: string,
   } {
     return {
       title: lockedString(UIStringsNotTranslate.lookingUpFunctionCode),
-      action: `getFunctionCode('${params.scriptUrl}', ${params.line}, ${params.column})`,
+      action: `getTraceFunctionCode('${params.scriptUrl}', ${params.line}, ${params.column})`,
     };
   }
 
   async handler(
-      params: GetFunctionCodeArgs,
+      params: GetTraceFunctionCodeArgs,
       capabilities: BaseToolCapability&PerformanceTraceCapability,
       ): Promise<DataHandlerResult<string>> {
     const performanceTraceContext = capabilities.getPerformanceTraceContext();

package/front_end/models/ai_assistance/tools/{GetResourceContent.ts → GetTraceResourceContent.ts}

@@ -25,42 +25,57 @@ const UIStringsNotTranslate = {
 
 const lockedString = i18n.i18n.lockedString;
 
-export interface GetResourceContentArgs extends ToolArgs {
+/**
+ * Arguments for {@link GetTraceResourceContentTool}.
+ */
+export interface GetTraceResourceContentArgs extends ToolArgs {
+  /** The URL of the resource captured in the performance trace to retrieve. */
   url: string;
 }
 
-export class GetResourceContentTool implements DataTool<
-    GetResourceContentArgs, {content: string}, BaseToolCapability&TargetCapability&PerformanceTraceCapability> {
-  readonly name: ToolName = ToolName.GET_RESOURCE_CONTENT;
+/**
+ * Retrieves text content for a resource or script captured in the performance trace.
+ *
+ * Precedence:
+ * 1. Checks trace metadata (`parsedTrace.data.Scripts`) for scripts captured during recording.
+ * 2. Falls back to querying the live page target's `ResourceTreeModel`.
+ *
+ * Preconditions:
+ * - Requires an active, freshly recorded trace session (fails on imported traces).
+ * - Fails if resource is binary/non-text, cross-origin, or a `file://` URL.
+ */
+export class GetTraceResourceContentTool implements DataTool<
+    GetTraceResourceContentArgs, {content: string}, BaseToolCapability&TargetCapability&PerformanceTraceCapability> {
+  readonly name: ToolName = ToolName.GET_TRACE_RESOURCE_CONTENT;
   readonly description: string =
-      'Retrieves the content of the resource with the given url. Only use this for text resource types.';
+      'Retrieves the text content of a script or resource captured within the recorded performance trace by URL. Only use this for text resource types. Do not call this tool on imported traces or for general workspace files (use listSources and getSourceContent instead).';
 
-  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetResourceContentArgs> = {
+  readonly parameters: Host.AidaClient.FunctionObjectParam<keyof GetTraceResourceContentArgs> = {
     type: Host.AidaClient.ParametersTypes.OBJECT,
-    description: 'Arguments for looking up resource content.',
+    description: 'Arguments for looking up resource content from the performance trace.',
     nullable: false,
     properties: {
       url: {
         type: Host.AidaClient.ParametersTypes.STRING,
-        description: 'The url for the resource.',
+        description: 'The URL of the resource captured in the performance trace to retrieve.',
         nullable: false,
       },
     },
     required: ['url'],
   };
 
-  displayInfoFromArgs(params: GetResourceContentArgs): {
+  displayInfoFromArgs(params: GetTraceResourceContentArgs): {
     title: string,
     action: string,
   } {
     return {
       title: lockedString(UIStringsNotTranslate.lookingAtResourceContent),
-      action: `getResourceContent('${params.url}')`,
+      action: `getTraceResourceContent('${params.url}')`,
     };
   }
 
   async handler(
-      params: GetResourceContentArgs,
+      params: GetTraceResourceContentArgs,
       capabilities: BaseToolCapability&TargetCapability&PerformanceTraceCapability,
       ): Promise<DataHandlerResult<{content: string}>> {
     const performanceTraceContext = capabilities.getPerformanceTraceContext();
@@ -72,6 +87,10 @@ export class GetResourceContentTool implements DataTool<
       return {error: 'Cannot use this tool on an imported file.'};
     }
 
+    if (!params.url) {
+      return {error: 'Missing arg: url'};
+    }
+
     if (!performanceTraceContext.canAccessResource(params.url)) {
       return {error: 'Resource not found'};
     }
@@ -82,6 +101,7 @@ export class GetResourceContentTool implements DataTool<
     let content: string;
 
     const url = params.url as Platform.DevToolsPath.UrlString;
+    // Check trace metadata for scripts captured during recording before falling back to live page resources.
     const script = parsedTrace.data.Scripts?.scripts.find(script => script.url === params.url);
     if (script?.content !== undefined) {
       content = script.content;