chrome-devtools-frontend 1.0.1713292 → 1.0.1715126

package/AUTHORS

@@ -53,6 +53,7 @@ Han Xu <suyanhanx@gmail.com>
 Helmut Januschka <helmut@januschka.com>
 Henry Lim <henry@limhenry.xyz>
 Hojeong Park <parkhj062@gmail.com>
+Hubert Gajewski <hubert@hubertgajewski.com>
 Ivan Akulov <gxoptg@gmail.com>
 Jacky Hu <flameddd@gmail.com>
 Jake Mulhern <mulherje@gmail.com>

package/DIR_METADATA

@@ -4,11 +4,9 @@ buganizer_public: {
 }
 agentic_review: {
   capability_groups: {
-    name: "core-review"
     review_capability_skills: [".agents/skills/code-review/SKILL.md"]
   }
   capability_groups: {
-    name: "typescript-and-models"
     path_expression: ["front_end/.*\\.ts", ".*BUILD\\.gn", ".*\\.gni"]
     path_expression_exclusion: [".*\\.test\\.ts"]
     review_capability_skills: [
@@ -20,7 +18,6 @@ agentic_review: {
     ]
   }
   capability_groups: {
-    name: "ui-and-widgets"
     path_expression: ["front_end/(panels|ui)/.*\\.(ts|css)"]
     path_expression_exclusion: [".*\\.test\\.ts"]
     review_capability_skills: [
@@ -29,7 +26,6 @@ agentic_review: {
     ]
   }
   capability_groups: {
-    name: "tests"
     path_expression: [".*\\.test\\.ts", "test/.*\\.ts"]
     review_capability_skills: [
       ".agents/skills/devtools-testing-guidance/SKILL.md",

package/eslint.config.mjs

@@ -375,6 +375,7 @@ export default defineConfig([
         'error',
         {
           argsIgnorePattern: '^_',
+          ignoreUsingDeclarations: true,
         },
       ],
 

package/front_end/core/sdk/CSSPropertyParserMatchers.ts

@@ -85,7 +85,10 @@ export class BaseVariableMatcher extends BaseVariableMatcherBase {
       return null;
     }
     const nameNode = args[0][0];
-    const fallback = args.length === 2 ? args[1] : undefined;
+    // Skip the first comma and closing parenthesis, preserving commas in the fallback.
+    const fallback = args.length > 1 ?
+        Array.from(ASTUtils.stripComments(ASTUtils.siblings(nameNode.nextSibling))).slice(1, -1) :
+        undefined;
 
     if (!isVariableNameNode(nameNode, matching.ast)) {
       return null;

package/front_end/core/sdk/DebuggerModel.ts

@@ -134,10 +134,14 @@ export const enum StepMode {
   STEP_OVER = 'StepOver',
 }
 
-/** A CDP step command. `ranges` is passed as `skipList` to stepInto/stepOver, and ignored for stepOut. */
+/**
+ * A CDP step command. `ranges` is passed as `skipList` to stepInto/stepOver, and ignored for stepOut. `enterRanges` is
+ * passed as `enterRanges` to stepOver: functions within them are entered as if by stepInto.
+ */
 export interface AutoStep {
   readonly command: StepMode;
   readonly ranges: readonly LocationRange[];
+  readonly enterRanges?: readonly LocationRange[];
 }
 
 /**
@@ -478,20 +482,25 @@ export class DebuggerModel extends SDKModel<EventTypes> {
     this.#issueStep(step, breakOnAsyncCall);
   }
 
-  #issueStep({command, ranges}: AutoStep, breakOnAsyncCall = false): void {
-    const skipList =
-        sortAndMergeRanges(ranges.map(({start, end}) => ({
-                                        scriptId: start.scriptId,
-                                        start: {lineNumber: start.lineNumber, columnNumber: start.columnNumber},
-                                        end: {lineNumber: end.lineNumber, columnNumber: end.columnNumber},
-                                      })));
+  #issueStep({command, ranges, enterRanges}: AutoStep, breakOnAsyncCall = false): void {
+    const toProtocolRange = ({start, end}: LocationRange): Protocol.Debugger.LocationRange => ({
+      scriptId: start.scriptId,
+      start: {lineNumber: start.lineNumber, columnNumber: start.columnNumber},
+      end: {lineNumber: end.lineNumber, columnNumber: end.columnNumber},
+    });
+    const skipList = sortAndMergeRanges(ranges.map(toProtocolRange));
     switch (command) {
       case StepMode.STEP_INTO:
         void this.agent.invoke_stepInto({breakOnAsyncCall, skipList});
         break;
-      case StepMode.STEP_OVER:
-        void this.agent.invoke_stepOver({skipList});
+      case StepMode.STEP_OVER: {
+        const request: Protocol.Debugger.StepOverRequest = {skipList};
+        if (enterRanges?.length) {
+          request.enterRanges = sortAndMergeRanges(enterRanges.map(toProtocolRange));
+        }
+        void this.agent.invoke_stepOver(request);
         break;
+      }
       case StepMode.STEP_OUT:
         void this.agent.invoke_stepOut();
         break;

package/front_end/core/sdk/PageFunctions.ts

@@ -109,7 +109,12 @@ export function toggleClassAndInjectStyleRule(this: Element, pseudoElementName:
   const classNamePrefix = '__web-inspector-hide';
   const classNameSuffix = '-shortcut__';
   const styleTagId = '__web-inspector-hide-shortcut-style__';
-  const pseudoElementNameEscaped = pseudoElementName ? pseudoElementName.replace(/[^a-zA-Z0-9_-]/g, '_') : '';
+  let pseudoElementNameEscaped = '';
+  if (pseudoElementName) {
+    pseudoElementNameEscaped = pseudoElementName.replace(/[^a-zA-Z0-9-]/g, function(c) {
+      return '_' + c.charCodeAt(0).toString(16) + '_';
+    });
+  }
   const className = classNamePrefix + pseudoElementNameEscaped + classNameSuffix;
   this.classList.toggle(className, hidden);
 
@@ -117,7 +122,7 @@ export function toggleClassAndInjectStyleRule(this: Element, pseudoElementName:
   while (localRoot.parentNode) {
     localRoot = (localRoot.parentNode as Element);
   }
-  if (localRoot.nodeType === Node.DOCUMENT_NODE) {
+  if (localRoot.nodeType === 9 /* Node.DOCUMENT_NODE */) {
     localRoot = document.head;
   }
 

package/front_end/core/sdk/ServerSentEventsProtocol.ts

@@ -95,8 +95,10 @@ export class ServerSentEventsParser {
       this.#data += '\n';
     }
     if (fieldName === 'id') {
-      // We should do a check here whether the id field contains "\0" and ignore it.
-      this.#id = this.#line.substring(fieldValueStart);
+      const id = this.#line.substring(fieldValueStart);
+      if (!id.includes('\0')) {
+        this.#id = id;
+      }
     }
     // Ignore all other fields. Also ignore "retry", we won't forward that to the backend.
   }

package/front_end/core/sdk/SourceMap.ts

@@ -900,11 +900,6 @@ export class SourceMap {
                                         [];
   }
 
-  /** See {@link SourceMapScopesInfo.hasOutlinedFunctions}. False without encoded scopes. */
-  hasOutlinedFunctions(): boolean {
-    return this.hasEncodedScopeInfo() && (this.#scopesInfo?.hasOutlinedFunctions() ?? false);
-  }
-
   /** See {@link SourceMapScopesInfo.outlinedFunctionRanges}. Empty without encoded scopes. */
   outlinedFunctionRanges(generatedLine: number, generatedColumn: number): PositionRange[] {
     return this.hasEncodedScopeInfo() ? this.#scopesInfo?.outlinedFunctionRanges(generatedLine, generatedColumn) ?? [] :

package/front_end/core/sdk/SourceMapScopesInfo.ts

@@ -613,17 +613,6 @@ export class SourceMapScopesInfo {
     return result;
   }
 
-  /**
-   * @returns true, iff any generated function is outlined, i.e. marked as "hidden" but with a definition (see
-   *          {@link GeneratedFrameKind.OUTLINED}). Hidden functions without a definition are compiler helpers.
-   */
-  hasOutlinedFunctions(): boolean {
-    const hasOutlined = (ranges: ScopesCodec.GeneratedRange[]): boolean =>
-        ranges.some(range => (range.isStackFrame && range.isHidden && range.originalScope !== undefined) ||
-                        hasOutlined(range.children));
-    return hasOutlined(this.#generatedRanges);
-  }
-
   /**
    * @returns the outlined parts of the authored function at the position: the hidden generated functions whose
    *          original scope lies within that function's original scope (see {@link GeneratedFrameKind.OUTLINED}).

package/front_end/generated/Deprecation.ts

@@ -242,6 +242,10 @@ export const UIStrings = {
    * @description A deprecation warning shown in the DevTools Issues tab. It's shown when a video conferencing website uses a non-standard API for controlling the crypto method used, but is not having an effect because the desired behavior is already enabled-by-default.
    */
   RTCConstraintEnableDtlsSrtpTrue: "The constraint `DtlsSrtpKeyAgreement` is removed. You have specified a `true` value for this constraint, which had no effect, but you can remove this constraint for tidiness.",
+  /**
+   * @description Warning displayed to developers when the non-standard RTCPeerConnection.createDTMFSender() method is used. Developers should use the standard RTCRtpSender.dtmf attribute instead.
+   */
+  RTCPeerConnectionCreateDTMFSender: "RTCPeerConnection.createDTMFSender() is deprecated and will be removed. Please use RTCRtpSender.dtmf instead.",
   /**
    * @description WebRTC is set of JavaScript APIs for sending and receiving data, audio and video. getStats() is a method used to obtain network and quality metrics. There are two versions of this method, one is being deprecated because it is non-standard.
    */
@@ -427,6 +431,10 @@ export const DEPRECATIONS_METADATA: Partial<Record<string, DeprecationDescriptor
   "RTCConstraintEnableDtlsSrtpTrue": {
     "milestone": 97
   },
+  "RTCPeerConnectionCreateDTMFSender": {
+    "chromeStatusFeature": 5160724576993280,
+    "milestone": 160
+  },
   "RTCPeerConnectionGetStatsLegacyNonCompliant": {
     "chromeStatusFeature": 4631626228695040,
     "milestone": 117

package/front_end/generated/InspectorBackendCommands.ts

@@ -89,7 +89,7 @@ inspectorBackend.registerEnum("Audits.SharedDictionaryError", {UseErrorCrossOrig
 inspectorBackend.registerEnum("Audits.SRIMessageSignatureError", {MissingSignatureHeader: "MissingSignatureHeader", MissingSignatureInputHeader: "MissingSignatureInputHeader", InvalidSignatureHeader: "InvalidSignatureHeader", InvalidSignatureInputHeader: "InvalidSignatureInputHeader", SignatureHeaderValueIsNotByteSequence: "SignatureHeaderValueIsNotByteSequence", SignatureHeaderValueIsParameterized: "SignatureHeaderValueIsParameterized", SignatureHeaderValueIsIncorrectLength: "SignatureHeaderValueIsIncorrectLength", SignatureInputHeaderMissingLabel: "SignatureInputHeaderMissingLabel", SignatureInputHeaderValueNotInnerList: "SignatureInputHeaderValueNotInnerList", SignatureInputHeaderValueMissingComponents: "SignatureInputHeaderValueMissingComponents", SignatureInputHeaderInvalidComponentType: "SignatureInputHeaderInvalidComponentType", SignatureInputHeaderInvalidComponentName: "SignatureInputHeaderInvalidComponentName", SignatureInputHeaderInvalidHeaderComponentParameter: "SignatureInputHeaderInvalidHeaderComponentParameter", SignatureInputHeaderInvalidDerivedComponentParameter: "SignatureInputHeaderInvalidDerivedComponentParameter", SignatureInputHeaderKeyIdLength: "SignatureInputHeaderKeyIdLength", SignatureInputHeaderInvalidParameter: "SignatureInputHeaderInvalidParameter", SignatureInputHeaderMissingRequiredParameters: "SignatureInputHeaderMissingRequiredParameters", ValidationFailedSignatureExpired: "ValidationFailedSignatureExpired", ValidationFailedInvalidLength: "ValidationFailedInvalidLength", ValidationFailedSignatureMismatch: "ValidationFailedSignatureMismatch", ValidationFailedIntegrityMismatch: "ValidationFailedIntegrityMismatch", SignatureBaseUnknownDerivedComponent: "SignatureBaseUnknownDerivedComponent", SignatureBaseMissingHeader: "SignatureBaseMissingHeader", SignatureBaseInvalidUnencodedDigest: "SignatureBaseInvalidUnencodedDigest", SignatureBaseUnsupportedComponent: "SignatureBaseUnsupportedComponent"});
 inspectorBackend.registerEnum("Audits.UnencodedDigestError", {MalformedDictionary: "MalformedDictionary", UnknownAlgorithm: "UnknownAlgorithm", IncorrectDigestType: "IncorrectDigestType", IncorrectDigestLength: "IncorrectDigestLength"});
 inspectorBackend.registerEnum("Audits.ConnectionAllowlistError", {InvalidHeader: "InvalidHeader", MoreThanOneList: "MoreThanOneList", ItemNotInnerList: "ItemNotInnerList", InvalidAllowlistItemType: "InvalidAllowlistItemType", ReportingEndpointNotToken: "ReportingEndpointNotToken", InvalidUrlPattern: "InvalidUrlPattern", IFrameAttributeLoosensEmbeddingRequirement: "IFrameAttributeLoosensEmbeddingRequirement", InvalidAllowConnectionAllowlistFrom: "InvalidAllowConnectionAllowlistFrom", EmbeddingRequirementNotSatisfied: "EmbeddingRequirementNotSatisfied"});
-inspectorBackend.registerEnum("Audits.GenericIssueErrorType", {FormLabelForNameError: "FormLabelForNameError", FormDuplicateIdForInputError: "FormDuplicateIdForInputError", FormInputWithNoLabelError: "FormInputWithNoLabelError", FormAutocompleteAttributeEmptyError: "FormAutocompleteAttributeEmptyError", FormEmptyIdAndNameAttributesForInputError: "FormEmptyIdAndNameAttributesForInputError", FormAriaLabelledByToNonExistingIdError: "FormAriaLabelledByToNonExistingIdError", FormInputAssignedAutocompleteValueToIdOrNameAttributeError: "FormInputAssignedAutocompleteValueToIdOrNameAttributeError", FormLabelHasNeitherForNorNestedInputError: "FormLabelHasNeitherForNorNestedInputError", FormLabelForMatchesNonExistingIdError: "FormLabelForMatchesNonExistingIdError", FormInputHasWrongButWellIntendedAutocompleteValueError: "FormInputHasWrongButWellIntendedAutocompleteValueError", ResponseWasBlockedByORB: "ResponseWasBlockedByORB", NavigationEntryMarkedSkippable: "NavigationEntryMarkedSkippable", BackUINavigationWouldSkipAd: "BackUINavigationWouldSkipAd", AutofillAndManualTextPolicyControlledFeaturesInfo: "AutofillAndManualTextPolicyControlledFeaturesInfo", AutofillPolicyControlledFeatureInfo: "AutofillPolicyControlledFeatureInfo", ManualTextPolicyControlledFeatureInfo: "ManualTextPolicyControlledFeatureInfo", FormModelContextParameterMissingTitleAndDescription: "FormModelContextParameterMissingTitleAndDescription", FormModelContextMissingToolName: "FormModelContextMissingToolName", FormModelContextMissingToolDescription: "FormModelContextMissingToolDescription", FormModelContextRequiredParameterMissingName: "FormModelContextRequiredParameterMissingName", FormModelContextParameterMissingName: "FormModelContextParameterMissingName"});
+inspectorBackend.registerEnum("Audits.GenericIssueErrorType", {FormLabelForNameError: "FormLabelForNameError", FormDuplicateIdForInputError: "FormDuplicateIdForInputError", FormInputWithNoLabelError: "FormInputWithNoLabelError", FormAutocompleteAttributeEmptyError: "FormAutocompleteAttributeEmptyError", FormEmptyIdAndNameAttributesForInputError: "FormEmptyIdAndNameAttributesForInputError", FormAriaLabelledByToNonExistingIdError: "FormAriaLabelledByToNonExistingIdError", FormInputAssignedAutocompleteValueToIdOrNameAttributeError: "FormInputAssignedAutocompleteValueToIdOrNameAttributeError", FormLabelHasNeitherForNorNestedInputError: "FormLabelHasNeitherForNorNestedInputError", FormLabelForMatchesNonExistingIdError: "FormLabelForMatchesNonExistingIdError", FormInputHasWrongButWellIntendedAutocompleteValueError: "FormInputHasWrongButWellIntendedAutocompleteValueError", ResponseWasBlockedByORB: "ResponseWasBlockedByORB", NavigationEntryMarkedSkippable: "NavigationEntryMarkedSkippable", BackUINavigationWouldSkipAd: "BackUINavigationWouldSkipAd", AutofillAndManualTextPolicyControlledFeaturesInfo: "AutofillAndManualTextPolicyControlledFeaturesInfo", AutofillPolicyControlledFeatureInfo: "AutofillPolicyControlledFeatureInfo", ManualTextPolicyControlledFeatureInfo: "ManualTextPolicyControlledFeatureInfo", FormModelContextParameterMissingTitleAndDescription: "FormModelContextParameterMissingTitleAndDescription", FormModelContextMissingToolName: "FormModelContextMissingToolName", FormModelContextMissingToolDescription: "FormModelContextMissingToolDescription", FormModelContextRequiredParameterMissingName: "FormModelContextRequiredParameterMissingName", FormModelContextParameterMissingName: "FormModelContextParameterMissingName", GeolocationPromptWithoutUserGesture: "GeolocationPromptWithoutUserGesture"});
 inspectorBackend.registerEnum("Audits.ClientHintIssueReason", {MetaTagAllowListInvalidOrigin: "MetaTagAllowListInvalidOrigin", MetaTagModifiedHTML: "MetaTagModifiedHTML"});
 inspectorBackend.registerEnum("Audits.FederatedAuthRequestIssueReason", {ShouldEmbargo: "ShouldEmbargo", TooManyRequests: "TooManyRequests", WellKnownHttpNotFound: "WellKnownHttpNotFound", WellKnownNoResponse: "WellKnownNoResponse", WellKnownBlockedByConnectionAllowlist: "WellKnownBlockedByConnectionAllowlist", WellKnownInvalidResponse: "WellKnownInvalidResponse", WellKnownListEmpty: "WellKnownListEmpty", WellKnownInvalidContentType: "WellKnownInvalidContentType", ConfigNotInWellKnown: "ConfigNotInWellKnown", WellKnownTooBig: "WellKnownTooBig", ConfigHttpNotFound: "ConfigHttpNotFound", ConfigNoResponse: "ConfigNoResponse", ConfigBlockedByConnectionAllowlist: "ConfigBlockedByConnectionAllowlist", ConfigInvalidResponse: "ConfigInvalidResponse", ConfigInvalidContentType: "ConfigInvalidContentType", IdpNotPotentiallyTrustworthy: "IdpNotPotentiallyTrustworthy", DisabledInSettings: "DisabledInSettings", DisabledInFlags: "DisabledInFlags", ErrorFetchingSignin: "ErrorFetchingSignin", InvalidSigninResponse: "InvalidSigninResponse", AccountsHttpNotFound: "AccountsHttpNotFound", AccountsNoResponse: "AccountsNoResponse", AccountsBlockedByConnectionAllowlist: "AccountsBlockedByConnectionAllowlist", AccountsInvalidResponse: "AccountsInvalidResponse", AccountsListEmpty: "AccountsListEmpty", AccountsInvalidContentType: "AccountsInvalidContentType", IdTokenHttpNotFound: "IdTokenHttpNotFound", IdTokenNoResponse: "IdTokenNoResponse", IdTokenBlockedByConnectionAllowlist: "IdTokenBlockedByConnectionAllowlist", IdTokenInvalidResponse: "IdTokenInvalidResponse", IdTokenIdpErrorResponse: "IdTokenIdpErrorResponse", IdTokenCrossSiteIdpErrorResponse: "IdTokenCrossSiteIdpErrorResponse", IdTokenInvalidRequest: "IdTokenInvalidRequest", IdTokenInvalidContentType: "IdTokenInvalidContentType", ErrorIdToken: "ErrorIdToken", Canceled: "Canceled", RpPageNotVisible: "RpPageNotVisible", SilentMediationFailure: "SilentMediationFailure", NotSignedInWithIdp: "NotSignedInWithIdp", MissingTransientUserActivation: "MissingTransientUserActivation", ReplacedByActiveMode: "ReplacedByActiveMode", RelyingPartyOriginIsOpaque: "RelyingPartyOriginIsOpaque", TypeNotMatching: "TypeNotMatching", UiDismissedNoEmbargo: "UiDismissedNoEmbargo", CorsError: "CorsError", SuppressedBySegmentationPlatform: "SuppressedBySegmentationPlatform", PopupBlockedByConnectionAllowlist: "PopupBlockedByConnectionAllowlist"});
 inspectorBackend.registerEnum("Audits.FederatedAuthUserInfoRequestIssueReason", {NotSameOrigin: "NotSameOrigin", NotIframe: "NotIframe", NotPotentiallyTrustworthy: "NotPotentiallyTrustworthy", NoAPIPermission: "NoApiPermission", NotSignedInWithIdp: "NotSignedInWithIdp", NoAccountSharingPermission: "NoAccountSharingPermission", InvalidConfigOrWellKnown: "InvalidConfigOrWellKnown", InvalidAccountsResponse: "InvalidAccountsResponse", NoReturningUserFromFetchedAccounts: "NoReturningUserFromFetchedAccounts"});
@@ -1126,6 +1126,7 @@ inspectorBackend.registerCommand("Page.getAppId", [], ["appId", "recommendedId",
 inspectorBackend.registerCommand("Page.getSubApps", [], ["subApps"], "Returns the list of installed child Sub-Apps for the inspected parent app.");
 inspectorBackend.registerCommand("Page.getSiblingSubApps", [], ["subApps"], "Returns the list of sibling Sub-Apps sharing the same parent app if the inspected context is a Sub-App.");
 inspectorBackend.registerCommand("Page.getAdScriptAncestry", [{"name": "frameId", "type": "string", "optional": false, "description": "", "typeRef": "Page.FrameId"}], ["adScriptAncestry"], "");
+inspectorBackend.registerCommand("Page.getSpellCheckCustomDictionary", [{"name": "frameId", "type": "string", "optional": false, "description": "", "typeRef": "Page.FrameId"}], ["words"], "Returns the words that the frame's document added to its spell check custom dictionary with `document.spellCheckCustomDictionary.addWords()`, sorted. Page script cannot read the dictionary back; this lets developers inspect it.");
 inspectorBackend.registerCommand("Page.getFrameTree", [], ["frameTree"], "Returns present frame tree structure.");
 inspectorBackend.registerCommand("Page.getLayoutMetrics", [], ["layoutViewport", "visualViewport", "contentSize", "cssLayoutViewport", "cssVisualViewport", "cssContentSize"], "Returns metrics relating to the layouting of the page, such as viewport bounds/scale.");
 inspectorBackend.registerCommand("Page.getNavigationHistory", [], ["currentIndex", "entries"], "Returns navigation history for the current page.");

package/front_end/generated/protocol-mapping.d.ts

@@ -4228,6 +4228,16 @@ export namespace ProtocolMapping {
       paramsType: [Protocol.Page.GetAdScriptAncestryRequest];
       returnType: Protocol.Page.GetAdScriptAncestryResponse;
     };
+    /**
+     * Returns the words that the frame's document added to its spell check custom
+     * dictionary with `document.spellCheckCustomDictionary.addWords()`, sorted.
+     * Page script cannot read the dictionary back; this lets developers inspect
+     * it.
+     */
+    'Page.getSpellCheckCustomDictionary': {
+      paramsType: [Protocol.Page.GetSpellCheckCustomDictionaryRequest];
+      returnType: Protocol.Page.GetSpellCheckCustomDictionaryResponse;
+    };
     /**
      * Returns present frame tree structure.
      */

package/front_end/generated/protocol-proxy-api.d.ts

@@ -3422,6 +3422,14 @@ declare namespace ProtocolProxyApi {
 
     invoke_getAdScriptAncestry(params: Protocol.Page.GetAdScriptAncestryRequest): Promise<Protocol.Page.GetAdScriptAncestryResponse>;
 
+    /**
+     * Returns the words that the frame's document added to its spell check custom
+     * dictionary with `document.spellCheckCustomDictionary.addWords()`, sorted.
+     * Page script cannot read the dictionary back; this lets developers inspect
+     * it.
+     */
+    invoke_getSpellCheckCustomDictionary(params: Protocol.Page.GetSpellCheckCustomDictionaryRequest): Promise<Protocol.Page.GetSpellCheckCustomDictionaryResponse>;
+
     /**
      * Returns present frame tree structure.
      */

package/front_end/generated/protocol.ts

@@ -1291,6 +1291,7 @@ export namespace Audits {
     FormModelContextMissingToolDescription = 'FormModelContextMissingToolDescription',
     FormModelContextRequiredParameterMissingName = 'FormModelContextRequiredParameterMissingName',
     FormModelContextParameterMissingName = 'FormModelContextParameterMissingName',
+    GeolocationPromptWithoutUserGesture = 'GeolocationPromptWithoutUserGesture',
   }
 
   /**
@@ -16027,6 +16028,14 @@ export namespace Page {
     adScriptAncestry?: Network.AdAncestry;
   }
 
+  export interface GetSpellCheckCustomDictionaryRequest {
+    frameId: FrameId;
+  }
+
+  export interface GetSpellCheckCustomDictionaryResponse extends ProtocolResponseWithError {
+    words: string[];
+  }
+
   export interface GetFrameTreeResponse extends ProtocolResponseWithError {
     /**
      * Present frame tree structure.

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

@@ -23,6 +23,65 @@ import {
 type UrlString = Platform.DevToolsPath.UrlString;
 const MAX_SUGGESTION_LENGTH = 200;
 
+/**
+ * The types of event in the response stream that `AiConversation#run()`
+ * yields to the AI assistance panel. The same events, minus a few, are saved
+ * as the conversation history and replayed when a saved conversation opens.
+ *
+ * ## Order of events in one run
+ *
+ * ```
+ * USER_QUERY                    (AiConversation, first run of a query only)
+ * CONTEXT*                      (agent's handleContextDetails())
+ * repeated for each model request, up to MAX_STEPS:
+ *   QUERYING
+ *   one of:
+ *     ANSWER (complete: false)*, ANSWER (complete: true)   text-only reply; the run ends
+ *     [ANSWER (complete: true)], <tool call events>        function call, optionally with text
+ *     ERROR                                                the run ends
+ * ```
+ *
+ * An `ERROR` can also follow the tool call events, for example when the user
+ * aborts, the page navigates cross-origin, or the run reaches `MAX_STEPS`.
+ *
+ * ## Events for one tool call
+ *
+ * `AiAgent#callFunction()` yields these. All events for one call carry the
+ * same `callId`.
+ *
+ * ```
+ * TITLE?, THOUGHT?              from the tool's displayInfoFromArgs()
+ * if the tool needs approval:
+ *   ACTION {code}               code only, shown above the approval prompt;
+ *                               skipped if displayInfoFromArgs() has no action
+ *   SIDE_EFFECT                 the panel shows the prompt and calls confirm()
+ *   if denied: ACTION {code, output, canceled: true}, and the call ends
+ * ACTION {code, output, widgets, toolName}   result or error
+ * ```
+ *
+ * If the tool switches context instead of returning a result, there is no
+ * result `ACTION`. `AiAgent#run()` yields `CONTEXT_CHANGE` and returns, and
+ * `AiConversation` starts a new run with the agent for the new context.
+ *
+ * ## Saved history
+ *
+ * `AiConversation` saves every event except `CONTEXT_CHANGE` and partial
+ * `ANSWER`s. `AiConversation#serialize()` removes `confirm`, images and
+ * widgets, and redacts the `ACTION` output of tools annotated with
+ * `REDACT_FROM_HISTORY`. Saved data has no version field, so new fields must
+ * be optional.
+ *
+ * ## How the panel renders events
+ *
+ * `AiAssistancePanel#consumeResponseStream()` builds one chat message per
+ * `USER_QUERY` and one step per tool call:
+ * - `QUERYING` starts a new step with a spinner. The panel shows the step only
+ *   if it is the first part of the message. Otherwise, the step stays hidden
+ *   until a tool call fills it in.
+ * - `TITLE`, `THOUGHT`, `ACTION` and `SIDE_EFFECT` update the step for their
+ *   `callId`. Events saved before `callId` existed update the current step.
+ * - `ANSWER` adds the answer text. `ERROR` sets the message error.
+ */
 export const enum ResponseType {
   CONTEXT = 'context',
   TITLE = 'title',
@@ -68,6 +127,10 @@ export interface AnswerResponse {
   widgets?: AiWidget[];
 }
 
+/**
+ * No agent yields this event. The panel still handles it by attaching the
+ * suggestions to the last answer.
+ */
 export interface SuggestionsResponse {
   type: ResponseType.SUGGESTIONS;
   suggestions: [string, ...string[]];
@@ -83,32 +146,79 @@ export interface ContextDetail {
   text: string;
   codeLang?: string;
 }
+
+/**
+ * Describes the context sent with the user's query, such as the selected
+ * element. The agent's `handleContextDetails()` yields it before the first
+ * model request. The panel shows it as a completed "Analyzing data" step.
+ */
 export interface ContextResponse {
   type: ResponseType.CONTEXT;
   details: [ContextDetail, ...ContextDetail[]];
   widgets?: AiWidget[];
 }
 
-export interface TitleResponse {
+/**
+ * Identifies the tool call that an event belongs to. `AiAgent#callFunction()`
+ * generates one per call and sets it on every event for that call. Only the
+ * UI reads it; the agent never sends it to the model.
+ *
+ * Conversations saved before this field existed do not have it. The panel
+ * applies events without a `callId` to the current step.
+ */
+interface ToolCallEvent {
+  callId?: string;
+}
+
+/**
+ * The heading of a tool call's step, from `displayInfoFromArgs().title`.
+ */
+export interface TitleResponse extends ToolCallEvent {
   type: ResponseType.TITLE;
   title: string;
+  /**
+   * No agent sets this field.
+   */
   rpcId?: Host.AidaClient.RpcGlobalId;
 }
 
-export interface ThoughtResponse {
+/**
+ * Explanation text for a tool call's step, from
+ * `displayInfoFromArgs().thought`. The panel marks the step as completed when
+ * it receives a thought, even though the tool has not run yet.
+ */
+export interface ThoughtResponse extends ToolCallEvent {
   type: ResponseType.THOUGHT;
   thought: string;
+  /**
+   * No agent sets this field.
+   */
   rpcId?: Host.AidaClient.RpcGlobalId;
 }
 
-export interface SideEffectResponse {
+/**
+ * Asks the user to approve a tool call that has side effects. The agent waits
+ * until `confirm()` is called. If `displayInfoFromArgs()` returns an
+ * `action`, the agent yields it in a code-only `ACTION` just before this
+ * event.
+ */
+export interface SideEffectResponse extends ToolCallEvent {
   type: ResponseType.SIDE_EFFECT;
   description: string|null;
+  /**
+   * No agent sets this field. The code comes from the preceding `ACTION`.
+   */
   code?: string;
   confirm: (decision: PermissionDecision) => void;
   permissionPrompt?: PermissionPrompt;
   permissionTitle?: string;
 }
+
+/**
+ * Yielded when a tool selects a new context, for example a network request.
+ * `AiConversation` switches to the agent for that context and starts a new
+ * run. `AiConversation` does not save this event in the history.
+ */
 export interface ContextChangeResponse {
   type: ResponseType.CONTEXT_CHANGE;
   /**
@@ -123,22 +233,51 @@ export interface ContextChangeResponse {
 
 interface SerializedSideEffectResponse extends Omit<SideEffectResponse, 'confirm'> {}
 
-export interface ActionResponse {
+/**
+ * The code and result of a tool call. A call yields one or two:
+ * - Calls that need approval and have code first yield a code-only `ACTION`
+ *   (no `output`), so the panel can show the code above the approval prompt.
+ * - Every call that runs, fails or is denied ends with an `ACTION` that has
+ *   an `output`.
+ */
+export interface ActionResponse extends ToolCallEvent {
   type: ResponseType.ACTION;
+  /**
+   * The text shown in the step's code box, from
+   * `displayInfoFromArgs().action`. It is real code only for tools that run
+   * code, such as `executeJavaScript`. For other tools it is a readable form of
+   * the call.
+   */
   code?: string;
+  /**
+   * The tool's result, error message, or the denial message. Missing on the
+   * code-only `ACTION` that precedes an approval prompt.
+   */
   output?: string;
+  /**
+   * True if the user denied the call, so the tool did not run.
+   */
   canceled: boolean;
   widgets?: AiWidget[];
   /**
-   * The name of the executed tool. Only populated for AI v2.
+   * The name of the tool. Set on the result `ACTION` but not on the code-only
+   * or denied `ACTION`. `AiConversation#serialize()` uses it to redact the
+   * output of tools annotated with `REDACT_FROM_HISTORY`.
    */
   toolName?: string;
 }
 
+/**
+ * Yielded before each model request. The panel starts a new step for it.
+ */
 export interface QueryingResponse {
   type: ResponseType.QUERYING;
 }
 
+/**
+ * The user's query. Yielded by `AiConversation`, not by the agent, before
+ * the first run for the query. The panel starts a new chat message for it.
+ */
 export interface UserQuery {
   type: ResponseType.USER_QUERY;
   query: string;
@@ -476,7 +615,17 @@ export interface FunctionDeclaration<Args extends Record<string, unknown>, Retur
    */
   parameters: Host.AidaClient.FunctionObjectParam<keyof Args>;
   /**
-   * Provided a way to give information back to the UI.
+   * Returns the text the UI shows for a call to this function. The agent
+   * calls it before the handler runs.
+   *
+   * - `title`: the step heading, sent as `TITLE`.
+   * - `thought`: optional explanation shown in the step, sent as `THOUGHT`.
+   * - `action`: the text shown in the step's code box, sent as
+   *   `ACTION.code`. It is real code only for tools that run code, such as
+   *   `executeJavaScript`. For other tools it is a readable form of the call,
+   *   for example `getInsightDetails('NAVIGATION_0', 'LCPBreakdown')`, and is
+   *   never executed.
+   * - `suggestions`: `AiAgent` does not use this field.
    */
   displayInfoFromArgs?: (
       args: Args,
@@ -981,6 +1130,17 @@ export abstract class AiAgent<T> {
               response: {...result, widgets: undefined},
             },
           };
+          if (i === MAX_STEPS - 1) {
+            // Normally, the functionResponse is pushed at the start of the next
+            // iteration. Since no further iteration will run, push it here so the
+            // last functionCall is not left unpaired in history.
+            this.#history.push({
+              parts: [query],
+              role: Host.AidaClient.Role.ROLE_UNSPECIFIED,
+            });
+            yield this.#createErrorResponse(ErrorType.MAX_STEPS);
+            break;
+          }
           request = this.buildRequest(query, Host.AidaClient.Role.ROLE_UNSPECIFIED);
         } catch (err) {
           if (err instanceof CrossOriginError) {
@@ -995,11 +1155,6 @@ export abstract class AiAgent<T> {
         yield this.#createErrorResponse(ErrorType.UNKNOWN);
         break;
       }
-
-      if (i === MAX_STEPS - 1) {
-        yield this.#createErrorResponse(ErrorType.MAX_STEPS);
-        break;
-      }
     }
 
     if (isStructuredLogEnabled()) {
@@ -1042,6 +1197,7 @@ export abstract class AiAgent<T> {
       role: Host.AidaClient.Role.MODEL,
     });
 
+    const callId = crypto.randomUUID();
     let code;
     if (call.displayInfoFromArgs) {
       const {title, thought, action: callCode} = call.displayInfoFromArgs(args);
@@ -1049,6 +1205,7 @@ export abstract class AiAgent<T> {
       if (title) {
         yield {
           type: ResponseType.TITLE,
+          callId,
           title,
         };
       }
@@ -1056,6 +1213,7 @@ export abstract class AiAgent<T> {
       if (thought) {
         yield {
           type: ResponseType.THOUGHT,
+          callId,
           thought,
         };
       }
@@ -1078,6 +1236,7 @@ export abstract class AiAgent<T> {
       if (code) {
         yield {
           type: ResponseType.ACTION,
+          callId,
           code,
           canceled: false,
         };
@@ -1104,6 +1263,7 @@ export abstract class AiAgent<T> {
 
       yield {
         type: ResponseType.SIDE_EFFECT,
+        callId,
         confirm: sideEffectConfirmationPromiseWithResolvers.resolve,
         description: result.description,
         permissionPrompt: call.permissionPrompt,
@@ -1119,6 +1279,7 @@ export abstract class AiAgent<T> {
       if (decision === PermissionDecision.REJECT) {
         yield {
           type: ResponseType.ACTION,
+          callId,
           code,
           output: 'Error: User denied code execution with side effects.',
           canceled: true,
@@ -1152,6 +1313,7 @@ export abstract class AiAgent<T> {
     if ('result' in result) {
       yield {
         type: ResponseType.ACTION,
+        callId,
         code,
         output: typeof result.result === 'string' ? result.result : JSON.stringify(result.result),
         widgets: result.widgets,
@@ -1163,6 +1325,7 @@ export abstract class AiAgent<T> {
     if ('error' in result) {
       yield {
         type: ResponseType.ACTION,
+        callId,
         code,
         output: result.error,
         canceled: false,
@@ -1228,8 +1391,11 @@ export abstract class AiAgent<T> {
   }
 
   #createErrorResponse(error: ErrorType): ResponseData {
-    this.#removeLastRunParts();
-    this.clearCache();
+    // If we hit MAX_STEPS, we still want to keep the call history as this may be relevant for follow-up requests.
+    if (error !== ErrorType.MAX_STEPS) {
+      this.#removeLastRunParts();
+      this.clearCache();
+    }
     if (error !== ErrorType.ABORT) {
       Host.userMetrics.actionTaken(Host.UserMetrics.Action.AiAssistanceError);
     }