chrome-devtools-frontend 1.0.1643855 → 1.0.1645245

package/front_end/core/host/UserMetrics.ts

@@ -496,8 +496,9 @@ export enum Action {
   AiCodeGenerationRequestTriggeredFromSources = 205,
   AiCodeCompletionFreCompletedFromConsole = 206,
   AiCodeCompletionFreCompletedFromSources = 207,
-  AiAssistanceOpenedFromStoragePanelFloatingButton = 208,
-  MAX_VALUE = 209,
+  AiAssistanceOpenedFromApplicationPanelFloatingButton = 208,
+  AiAssistanceOpenedFromApplicationPanel = 209,
+  MAX_VALUE = 210,
   /* eslint-enable @typescript-eslint/naming-convention */
 }
 

package/front_end/core/sdk/CSSPropertyParserMatchers.ts

@@ -561,9 +561,8 @@ export class ColorMatcher extends matcherBase(ColorMatch) {
         const colorText = args.length >= 2 ? matching.getComputedTextRange(args[0], args[args.length - 1]) : '';
         // colorText holds the fully substituted parenthesized expression, so colorFunc + colorText is the color
         // function call.
-        const isRelativeColorSyntax = Boolean(
-            colorText.match(/^[^)]*\(\W*from\W+/) && !matching.hasUnresolvedSubstitutions(node) &&
-            CSS.supports('color', colorFunc + colorText));
+        const isRelativeColorSyntax =
+            Boolean(colorText.match(/^[^)]*\(\W*from\W+/) && !matching.hasUnresolvedSubstitutions(node));
         if (!isRelativeColorSyntax) {
           return new ColorMatch(text, node);
         }

package/front_end/core/sdk/NetworkRequest.ts

@@ -1920,7 +1920,6 @@ export interface EventTypes {
   [Events.RESPONSE_HEADERS_CHANGED]: void;
   [Events.WEBSOCKET_FRAME_ADDED]: WebSocketFrame;
   [Events.DIRECTSOCKET_CHUNK_ADDED]: DirectSocketChunk;
-  [Events.DIRECTSOCKET_CHUNK_ADDED]: DirectSocketChunk;
   [Events.EVENT_SOURCE_MESSAGE_ADDED]: EventSourceMessage;
   [Events.TRUST_TOKEN_RESULT_ADDED]: void;
 }

package/front_end/entrypoints/heap_snapshot_worker/HeapSnapshot.ts

@@ -2740,6 +2740,8 @@ export abstract class HeapSnapshot {
       const nodeAId = baseIds[i];
       if (nodeAId < nodeB.id()) {
         diff.deletedIndexes.push(baseIndexes[i]);
+        diff.deletedIds.push(nodeAId);
+        diff.deletedSelfSizes.push(baseSelfSizes[i]);
         diff.removedCount++;
         diff.removedSize += baseSelfSizes[i];
         ++i;
@@ -2747,6 +2749,8 @@ export abstract class HeapSnapshot {
           nodeAId >
           nodeB.id()) {  // Native nodes(e.g. dom groups) may have ids less than max JS object id in the base snapshot
         diff.addedIndexes.push(indexes[j]);
+        diff.addedIds.push(nodeB.id());
+        diff.addedSelfSizes.push(nodeB.selfSize());
         diff.addedCount++;
         diff.addedSize += nodeB.selfSize();
         nodeB.nodeIndex = indexes[++j];
@@ -2757,12 +2761,16 @@ export abstract class HeapSnapshot {
     }
     while (i < l) {
       diff.deletedIndexes.push(baseIndexes[i]);
+      diff.deletedIds.push(baseIds[i]);
+      diff.deletedSelfSizes.push(baseSelfSizes[i]);
       diff.removedCount++;
       diff.removedSize += baseSelfSizes[i];
       ++i;
     }
     while (j < m) {
       diff.addedIndexes.push(indexes[j]);
+      diff.addedIds.push(nodeB.id());
+      diff.addedSelfSizes.push(nodeB.selfSize());
       diff.addedCount++;
       diff.addedSize += nodeB.selfSize();
       nodeB.nodeIndex = indexes[++j];
@@ -2975,6 +2983,35 @@ export abstract class HeapSnapshot {
     return {paths, limitsReached};
   }
 
+  getDominatorsOf(nodeIndex: number): HeapSnapshotModel.HeapSnapshotModel.DominatorChain {
+    const chain: HeapSnapshotModel.HeapSnapshotModel.DominatorNode[] = [];
+    let currentIndex = nodeIndex;
+    const rootIndex = this.rootNodeIndex;
+
+    while (currentIndex !== undefined) {
+      const node = this.createNode(currentIndex);
+      chain.push({
+        nodeId: node.id(),
+        nodeIndex: currentIndex,
+        nodeName: node.name(),
+        retainedSize: node.retainedSize(),
+        selfSize: node.selfSize(),
+      });
+
+      if (currentIndex === rootIndex) {
+        break;
+      }
+
+      const nextIndex = node.dominatorIndex();
+      if (nextIndex === currentIndex) {
+        break;
+      }
+      currentIndex = nextIndex;
+    }
+
+    return chain;
+  }
+
   createAddedNodesProvider(baseSnapshotId: number, classKey: string): HeapSnapshotNodesProvider {
     const snapshotDiff = this.#snapshotDiffs[baseSnapshotId];
     const diffForClass = snapshotDiff[classKey];

package/front_end/generated/SupportedCSSProperties.js

@@ -3860,7 +3860,8 @@ export const generatedProperties = [
  {
   "keywords": [
    "auto",
-   "none"
+   "none",
+   "normal"
   ],
   "name": "position-anchor"
  },
@@ -6987,7 +6988,8 @@ export const generatedPropertyValues = {
  "position-anchor": {
   "values": [
    "auto",
-   "none"
+   "none",
+   "normal"
   ]
  },
  "position-area": {

package/front_end/models/ai_assistance/AiAgent2.ts

@@ -3,9 +3,11 @@
 // found in the LICENSE file.
 
 import * as Host from '../../core/host/host.js';
+import * as SDK from '../../core/sdk/sdk.js';
 
 import {
   AiAgent,
+  type AllowedOriginResult,
   type ContextResponse,
   type ConversationContext,
   type MultimodalInputType,
@@ -19,7 +21,7 @@ import {debugLog} from './debug.js';
 import {ExtensionScope} from './ExtensionScope.js';
 import type {Skill, SkillName} from './skills/Skill.js';
 import {SKILLS} from './skills/SkillRegistry.js';
-import type {Tool} from './tools/Tool.js';
+import type {AllToolsContext, Tool, ToolArgs} from './tools/Tool.js';
 import {ToolRegistry} from './tools/ToolRegistry.js';
 
 const SKILL_DISPLAY_NAMES: Record<SkillName, string> = {
@@ -35,6 +37,7 @@ export class AiAgent2 extends AiAgent<unknown> {
   #skillsInjected = false;
   #changes = new ChangeManager();
   #execJs: typeof executeJsCode;
+  readonly #allowedOrigin?: () => AllowedOriginResult;
 
   get options(): RequestOptions {
     return {};
@@ -46,6 +49,7 @@ export class AiAgent2 extends AiAgent<unknown> {
   constructor(opts: ExecuteJsAgentOptions) {
     super(opts);
     this.#execJs = opts.execJs ?? executeJsCode;
+    this.#allowedOrigin = opts.allowedOrigin;
     this.#declaredTools.add('learnSkills');
     const skillsList = Object.keys(SKILLS).join(', ');
     this.declareFunction<{skills: SkillName[]}>('learnSkills', {
@@ -169,7 +173,7 @@ User query: ${enhancedQuery}`;
    * Declares a tool to be available to the agent model, verifying first that
    * it hasn't already been declared to prevent duplicate declaration errors.
    */
-  #declareTool(tool: Tool): void {
+  #declareTool(tool: Tool<ToolArgs, unknown, AllToolsContext>): void {
     if (this.#declaredTools.has(tool.name)) {
       debugLog(`AiAgent2: Tool ${tool.name} is already declared`);
       return;
@@ -179,20 +183,26 @@ User query: ${enhancedQuery}`;
       description: tool.description,
       parameters: tool.parameters,
       displayInfoFromArgs: tool.displayInfoFromArgs,
-      handler: (args, options) => tool.handler(
-          args,
-          {
-            conversationContext: this.context ?? null,
-            changeManager: this.#changes,
-            createExtensionScope: this.#createExtensionScope.bind(this),
-            execJs: this.#execJs,
-            getExecutionContextNode: () => this.context instanceof DOMNodeContext ? this.context.getItem() : null,
-          },
-          options,
-          ),
+      handler: (args, options) => {
+        const context: AllToolsContext = {
+          conversationContext: this.context ?? null,
+          changeManager: this.#changes,
+          createExtensionScope: this.#createExtensionScope.bind(this),
+          execJs: this.#execJs,
+          getExecutionContextNode: () => this.context instanceof DOMNodeContext ? this.context.getItem() : null,
+          getTarget: () => SDK.TargetManager.TargetManager.instance().primaryPageTarget(),
+          getEstablishedOrigin: () => this.#getConversationOrigin(),
+        };
+        return tool.handler(args, context, options);
+      },
     });
   }
 
+  #getConversationOrigin(): string|undefined {
+    const allowed = this.#allowedOrigin?.();
+    return allowed && 'origin' in allowed ? allowed.origin : undefined;
+  }
+
   get activeSkills(): Set<SkillName> {
     return this.#activeSkills;
   }

package/front_end/models/ai_assistance/README.md

@@ -24,7 +24,7 @@ To deal with the work to take an object that is the AI agent's context and turn
 
 ## Future Architecture (V2) - WIP
 
-We are currently working on migrating the DevTools AI Assistance from a siloed multi-agent architecture to a unified, skill-based single-agent architecture (`AIAgent2`).
+We are migrating the DevTools AI Assistance from a siloed multi-agent architecture to a unified, skill-based single-agent architecture (`AIAgent2`).
 
 In this new architecture:
 - A single agent (`AIAgent2`) handles multiple domains.
@@ -36,15 +36,16 @@ This work is currently in progress and behind a feature flag.
 ### Skills Build System
 
 To support dynamic loading of skills, we generate JavaScript files from Markdown files containing skill definitions.
-We use a nested `BUILD.gn` file in the `skills/` subdirectory specifically for this purpose. This ensures that GN's `target_gen_dir` points to `gen/front_end/models/ai_assistance/skills/`, placing the generated `.skill.js` files in the same relative structure as their source `.md` files. This allows TypeScript files in the `skills/` directory (like `map.ts`) to import the generated files using relative paths (e.g., `./styling.skill.js`) seamlessly.
+We use a nested `BUILD.gn` file in the `skills/` subdirectory specifically for this purpose. This ensures that GN's `target_gen_dir` points to `gen/front_end/models/ai_assistance/skills/`, placing the generated `.skill.js` files in the same relative structure as their source `.md` files. This allows TypeScript files in the `skills/` directory (like `map.ts`) to import the generated files using relative paths (e.g., `./styling.skill.js`) seamlessly. See the [Skills README](skills/README.md) for full details.
 
 ### Tools and ToolRegistry
 
 To support skills requiring execution of code or fetching page state (like computed styles), the architecture defines **Tools** in the `tools/` directory.
 
 - **BaseTool**: A non-generic base interface capturing tool metadata (`name`, `description`, `parameters`). This acts as the type-erased representation for generic registry storage and fallback string lookups.
-- **Tool**: A generic interface extending `BaseTool` that binds argument types (`Args`) to the schema `parameters` and the `handler()` method. This ensures compile-time safety and alignment inside each tool implementation.
-- **ToolRegistry**: A static registry (`ToolRegistry`) storing instantiated tools. It uses TypeScript function overloading and generic lookups (`static get<K extends keyof typeof TOOLS>(name: K): typeof TOOLS[K]`) to return the precise class type of each tool, preventing type-erasure and escape-hatches (such as `any` or `as unknown` type assertions) at integration points like `AiAgent.ts`.
+- **Tool**: A generic interface parameterized by `<Args, ReturnType, ContextType>` that binds parameter argument types and handler execution to strict contracts. `ContextType` defaults to `BaseToolCapability`, ensuring that each tool explicitly requests only the dependencies it requires.
+- **Capability Contexts**: Instead of passing a monolithic grab-bag context to all tools, dependencies are broken into narrow capability interfaces (e.g. `PageExecutionCapability`, `StyleMutationCapability`, `TargetCapability`, `OriginLockCapability`). Tools declare their required dependencies by intersecting these interfaces on their generic `ContextType` definition. The caller/Agent fulfills the complete capability context (`AllToolsContext`), guaranteeing 100% compile-time type safety for dependencies without runtime checks.
+- **ToolRegistry**: A static registry (`ToolRegistry`) storing instantiated tools. It uses TypeScript function overloading and generic lookups (`static get<K extends keyof typeof TOOLS>(name: K): typeof TOOLS[K]`) to return the precise class type of each tool, preventing type-erasure and escape-hatches (such as `any` or `as unknown` type assertions) at integration points like `AiAgent2.ts`. See the [Tools README](tools/README.md) for authoring instructions.
 
 ## Performance specific documentation
 

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

@@ -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 {

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

@@ -2,6 +2,35 @@
 
 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
+  }
+```
+
 ## 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 +99,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/tools/ExecuteJavaScript.ts

@@ -8,9 +8,11 @@ import type {FunctionCallHandlerResult, FunctionHandlerOptions,} from '../agents
 import {JavascriptExecutor} from '../agents/ExecuteJavascript.js';
 
 import {
+  type BaseToolCapability,
+  type PageExecutionCapability,
+  type StyleMutationCapability,
   type Tool,
   type ToolArgs,
-  type ToolContext,
   ToolName,
 } from './Tool.js';
 
@@ -20,7 +22,8 @@ export interface ExecuteJavaScriptArgs extends ToolArgs {
   title: string;
 }
 
-export class ExecuteJavaScriptTool implements Tool<ExecuteJavaScriptArgs, unknown> {
+export class ExecuteJavaScriptTool implements
+    Tool<ExecuteJavaScriptArgs, unknown, BaseToolCapability&PageExecutionCapability&StyleMutationCapability> {
   readonly name = ToolName.EXECUTE_JAVASCRIPT;
 
   readonly description =
@@ -104,10 +107,10 @@ const data = {
 
   async handler(
       params: ExecuteJavaScriptArgs,
-      context: ToolContext,
+      context: BaseToolCapability&PageExecutionCapability&StyleMutationCapability,
       options?: FunctionHandlerOptions,
       ): Promise<FunctionCallHandlerResult<unknown>> {
-    const executionNode = context.getExecutionContextNode?.() ?? null;
+    const executionNode = context.getExecutionContextNode();
     if (!executionNode) {
       return {error: 'Error: Could not find the context node for execution.'};
     }
@@ -115,17 +118,11 @@ const data = {
     const executionMode = Root.Runtime.hostConfig.devToolsFreestyler?.executionMode ??
         Root.Runtime.HostConfigFreestylerExecutionMode.ALL_SCRIPTS;
 
-    const changes = context.changeManager;
-    const createExtensionScope = context.createExtensionScope;
-    if (!changes || !createExtensionScope) {
-      return {error: 'Internal Error: Required change manager or extension scope creator is missing.'};
-    }
-
     const executor = new JavascriptExecutor({
       executionMode,
       getContextNode: () => executionNode,
-      createExtensionScope,
-      changes,
+      createExtensionScope: context.createExtensionScope,
+      changes: context.changeManager,
     },
                                             context.execJs);
 

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

@@ -9,7 +9,14 @@ import type {ComputedStyleAiWidget, FunctionCallHandlerResult, FunctionHandlerOp
 import {DOMNodeContext} from '../contexts/DOMNodeContext.js';
 import {debugLog} from '../debug.js';
 
-import {type Tool, type ToolArgs, type ToolContext, ToolName} from './Tool.js';
+import {
+  type BaseToolCapability,
+  type OriginLockCapability,
+  type TargetCapability,
+  type Tool,
+  type ToolArgs,
+  ToolName,
+} from './Tool.js';
 
 export interface GetStylesArgs extends ToolArgs {
   elements: number[];
@@ -17,7 +24,8 @@ export interface GetStylesArgs extends ToolArgs {
   explanation: string;
 }
 
-export class GetStylesTool implements Tool<GetStylesArgs, unknown> {
+export class GetStylesTool implements
+    Tool<GetStylesArgs, unknown, BaseToolCapability&TargetCapability&OriginLockCapability> {
   readonly name = ToolName.GET_STYLES;
   readonly description =
       `Get computed and source styles for one or multiple elements on the inspected page for multiple elements at once by uid.
@@ -71,34 +79,33 @@ export class GetStylesTool implements Tool<GetStylesArgs, unknown> {
 
   async handler(
       params: GetStylesArgs,
-      context: ToolContext,
+      context: BaseToolCapability&TargetCapability&OriginLockCapability,
       _options?: FunctionHandlerOptions,
       ): Promise<FunctionCallHandlerResult<unknown>> {
     const widgets: ComputedStyleAiWidget[] = [];
     const result:
         Record<string, {computed: Record<string, string|undefined>, authored: Record<string, string|undefined>}> = {};
 
-    const activeContext = context.conversationContext;
-    if (!activeContext || !(activeContext instanceof DOMNodeContext)) {
-      return {error: 'Error: Could not find the currently selected element.'};
+    const target = context.getTarget();
+    if (!target) {
+      return {error: 'Error: Could not find the inspected page.'};
     }
 
-    const selectedNode = activeContext.getItem();
-    if (!selectedNode) {
-      return {error: 'Error: Could not find the currently selected element.'};
+    const establishedOrigin = context.getEstablishedOrigin();
+    if (!establishedOrigin) {
+      return {error: 'Error: Origin lock is not established.'};
     }
 
     for (const uid of params.elements) {
       result[uid] = {computed: {}, authored: {}};
       debugLog(`Action to execute: uid=${uid}`);
-      const node =
-          new SDK.DOMModel.DeferredDOMNode(selectedNode.domModel().target(), uid as Protocol.DOM.BackendNodeId);
+      const node = new SDK.DOMModel.DeferredDOMNode(target, uid as Protocol.DOM.BackendNodeId);
       const resolved = await node.resolvePromise();
       if (!resolved) {
         return {error: 'Error: Could not find the element with uid=' + uid};
       }
       const newContext = new DOMNodeContext(resolved);
-      if (activeContext.getOrigin() !== newContext.getOrigin()) {
+      if (establishedOrigin !== newContext.getOrigin()) {
         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/README.md

@@ -0,0 +1,45 @@
+# AI Assistant Tools Architecture
+
+This directory defines the **Tools** used by `AiAgent2` and other AI agents to execute code, read page state, or apply mutations to the inspected page.
+
+## Core Concepts
+
+The architecture relies on three primary concepts to guarantee 100% compile-time type safety for tools:
+1. **BaseTool**: An interface capturing non-generic tool metadata (e.g. `name`, `description`, `parameters`). This allows the agent and DevTools UI to generically store, register, and describe functions to the AIDA client without needing to know their specific types at runtime.
+2. **Capability Interfaces**: Narrow TypeScript interfaces wrapping individual DevTools dependencies (e.g., ChangeManager, executeJsCode). This decouples tools from monolithic agent environments, making them reusable and easier to unit test.
+3. **Tool**: A generic TypeScript interface (`Tool<Args, ReturnType, ContextType>`) binding the execution handler to specific capability requirements. This enforces compile-time safety, ensuring that a tool handler is only invoked by an agent that fulfills all the required capabilities.
+
+## Capability Interfaces
+
+Instead of passing a monolithic "grab-bag" context object to all tool handlers, DevTools AI tools declare exactly the capabilities they require. Available capability interfaces defined in `Tool.ts` include:
+
+- `BaseToolCapability`: Base interface providing access to the top-level conversation context step.
+- `PageExecutionCapability`: For tools executing JavaScript code on the inspected page.
+- `StyleMutationCapability`: For tools managing and applying style mutations via a `ChangeManager`.
+- `TargetCapability`: For tools requiring access to the page's current SDK `Target`.
+- `OriginLockCapability`: For tools enforcing cross-origin security via origin locks.
+
+### Unified Context
+
+The Agent (e.g., `AiAgent2`) builds the complete dependency union (`AllToolsContext`) and fulfills all capabilities. When the handler is invoked, TypeScript validates that the provided context matches the intersection of capabilities requested by that tool.
+
+## Authoring a New Tool
+
+To author a new tool:
+
+1. **Define the Args interface**: Extend `ToolArgs` to represent the JSON parameter schema expected by the LLM.
+2. **Declare Capability Dependencies**: Determine which capabilities your tool handler needs. Intersect them to define the tool's `ContextType`.
+3. **Implement the `Tool` interface**: Pass the args interface, return type, and intersected ContextType to the generic parameters of `Tool`.
+4. **Instantiate in `ToolRegistry.ts`**: Add the instantiated tool class to the static `TOOLS` registry.
+
+See concrete, production examples of capability-based tools in this directory:
+- [ExecuteJavaScript.ts](ExecuteJavaScript.ts): Demonstrates use of `PageExecutionCapability` and `StyleMutationCapability`.
+- [GetStyles.ts](GetStyles.ts): Demonstrates use of `TargetCapability` and `OriginLockCapability`.
+
+## ToolRegistry Lookup
+
+To retrieve a tool from the registry with 100% type safety, call `ToolRegistry.get()` with the literal `ToolName` key:
+
+```typescript
+const getStylesTool = ToolRegistry.get(ToolName.GET_STYLES); // Returns GetStylesTool class type
+```