chrome-devtools-frontend 1.0.1643855 → 1.0.1646286

package/front_end/generated/SupportedCSSProperties.js

@@ -248,6 +248,8 @@ export const generatedProperties = [
   "name": "accent-color"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "additive-symbols"
  },
  {
@@ -933,6 +935,8 @@ export const generatedProperties = [
   "name": "appearance"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "ascent-override"
  },
  {
@@ -1053,9 +1057,13 @@ export const generatedProperties = [
   "name": "background-size"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "base-palette"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "base-url"
  },
  {
@@ -2338,6 +2346,8 @@ export const generatedProperties = [
   "name": "d"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "descent-override"
  },
  {
@@ -2418,6 +2428,8 @@ export const generatedProperties = [
   "name": "empty-cells"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "fallback"
  },
  {
@@ -2553,14 +2565,18 @@ export const generatedProperties = [
   "name": "font"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "font-display"
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "name": "font-family"
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "keywords": [
    "normal"
   ],
@@ -2631,6 +2647,7 @@ export const generatedProperties = [
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "keywords": [
    "normal",
    "ultra-condensed",
@@ -2646,6 +2663,7 @@ export const generatedProperties = [
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "keywords": [
    "normal",
    "italic",
@@ -2688,6 +2706,7 @@ export const generatedProperties = [
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "longhands": [
    "font-variant-ligatures",
    "font-variant-caps",
@@ -2787,6 +2806,7 @@ export const generatedProperties = [
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "keywords": [
    "normal"
   ],
@@ -2794,6 +2814,7 @@ export const generatedProperties = [
  },
  {
   "inherited": true,
+  "is_descriptor": true,
   "keywords": [
    "normal",
    "bold",
@@ -2972,6 +2993,8 @@ export const generatedProperties = [
   "name": "hanging-punctuation"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "hash"
  },
  {
@@ -2984,6 +3007,8 @@ export const generatedProperties = [
   "name": "height"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "hostname"
  },
  {
@@ -3033,6 +3058,8 @@ export const generatedProperties = [
   "name": "image-rendering"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "inherits"
  },
  {
@@ -3045,6 +3072,8 @@ export const generatedProperties = [
   "name": "initial-letter"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "initial-value"
  },
  {
@@ -3173,6 +3202,8 @@ export const generatedProperties = [
   "name": "line-clamp"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "line-gap-override"
  },
  {
@@ -3468,9 +3499,13 @@ export const generatedProperties = [
   "name": "mix-blend-mode"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "navigation"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "negative"
  },
  {
@@ -3657,6 +3692,8 @@ export const generatedProperties = [
   "name": "overlay"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "override-colors"
  },
  {
@@ -3691,6 +3728,8 @@ export const generatedProperties = [
   "name": "overscroll-behavior-y"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "pad"
  },
  {
@@ -3765,6 +3804,7 @@ export const generatedProperties = [
   "name": "page-break-inside"
  },
  {
+  "is_descriptor": true,
   "keywords": [
    "none",
    "clamp",
@@ -3773,6 +3813,7 @@ export const generatedProperties = [
   "name": "page-margin-safety"
  },
  {
+  "is_descriptor": true,
   "name": "page-orientation"
  },
  {
@@ -3792,9 +3833,13 @@ export const generatedProperties = [
   "name": "path-length"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "pathname"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "pattern"
  },
  {
@@ -3845,6 +3890,8 @@ export const generatedProperties = [
   "name": "pointer-events"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "port"
  },
  {
@@ -3860,7 +3907,8 @@ export const generatedProperties = [
  {
   "keywords": [
    "auto",
-   "none"
+   "none",
+   "normal"
   ],
   "name": "position-anchor"
  },
@@ -3921,6 +3969,8 @@ export const generatedProperties = [
   "name": "position-visibility"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "prefix"
  },
  {
@@ -3932,6 +3982,8 @@ export const generatedProperties = [
   "name": "print-color-adjust"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "protocol"
  },
  {
@@ -3946,6 +3998,8 @@ export const generatedProperties = [
   "name": "r"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "range"
  },
  {
@@ -3975,6 +4029,8 @@ export const generatedProperties = [
   "name": "resize"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "result"
  },
  {
@@ -4474,6 +4530,8 @@ export const generatedProperties = [
   "name": "scrollbar-width"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "search"
  },
  {
@@ -4505,6 +4563,8 @@ export const generatedProperties = [
   "name": "size"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "size-adjust"
  },
  {
@@ -4520,9 +4580,13 @@ export const generatedProperties = [
   "name": "speak"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "speak-as"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "src"
  },
  {
@@ -4580,15 +4644,23 @@ export const generatedProperties = [
   "name": "stroke-width"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "suffix"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "symbols"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "syntax"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "system"
  },
  {
@@ -5051,6 +5123,8 @@ export const generatedProperties = [
   "name": "trigger-scope"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "types"
  },
  {
@@ -5065,6 +5139,8 @@ export const generatedProperties = [
   "name": "unicode-bidi"
  },
  {
+  "is_descriptor": true,
+  "is_property": false,
   "name": "unicode-range"
  },
  {
@@ -6987,7 +7063,8 @@ export const generatedPropertyValues = {
  "position-anchor": {
   "values": [
    "auto",
-   "none"
+   "none",
+   "normal"
   ]
  },
  "position-area": {

package/front_end/generated/protocol.ts

@@ -11136,10 +11136,6 @@ export namespace Network {
   export const enum CookieExemptionReason {
     None = 'None',
     UserSetting = 'UserSetting',
-    TPCDMetadata = 'TPCDMetadata',
-    TPCDDeprecationTrial = 'TPCDDeprecationTrial',
-    TopLevelTPCDDeprecationTrial = 'TopLevelTPCDDeprecationTrial',
-    TPCDHeuristics = 'TPCDHeuristics',
     EnterprisePolicy = 'EnterprisePolicy',
     StorageAccess = 'StorageAccess',
     TopLevelStorageAccess = 'TopLevelStorageAccess',
@@ -14604,7 +14600,6 @@ export namespace Page {
     DigitalCredentialsGet = 'digital-credentials-get',
     DirectSockets = 'direct-sockets',
     DirectSocketsMulticast = 'direct-sockets-multicast',
-    DirectSocketsPrivate = 'direct-sockets-private',
     DisplayCapture = 'display-capture',
     DocumentDomain = 'document-domain',
     EncryptedMedia = 'encrypted-media',

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,22 +21,50 @@ 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> = {
   styling: 'CSS and styling',
 };
 
+const preamble = `You are the most advanced unified AI assistant integrated into Chrome DevTools.
+Your role is to help web developers debug, analyze, and optimize web applications by learning specialized skills and utilizing tools.
+
+# Style Guidelines
+* **Precision and Brevity**: Use the precision of Strunk & White, the brevity of Hemingway, and the simple clarity of Vonnegut. Keep answers short, direct, and avoid repeated information or filler.
+* **Tone**: Technical, precise, educational, and supportive.
+* **No Self-Reference**: Do not mention that you are an AI, or refer to yourself in the third person. Simulate a senior web development expert.
+* **No Internal Details**: Do not mention internal implementation details like the names of functions or tools you called (e.g., do not say "I called getStyles").
+
+# Workflow
+1. **Analyze**: Understand the user's intent, the context provided, and what they are trying to achieve.
+2. **Investigate**: Proactively use your learned skills and tools to gather live data. Do not make assumptions or guess without sufficient evidence.
+3. **Analyze**: Explore multiple potential explanations and solutions. Distinguish between the primary root cause and contributing factors.
+4. **Respond**: Provide a structured, clear, and actionable response.
+
+# Response Structure
+If the user asks a question that requires an investigation or debugging, use this structure:
+* **Root Cause(s)**: Point out the root cause(s) of the problem.
+  - Example: "**Root Cause**: [reason]" or "**Root Causes**:" followed by a bulleted list.
+* **Suggestion(s)**: List actionable solution suggestion(s) in order of impact.
+  - Example: "**Suggestion**: [Suggestion]" or "**Suggestions**:" followed by a bulleted list.
+
+# Constraints
+* **CRITICAL**: You are a web development assistant. NEVER provide answers to questions of unrelated topics (such as legal advice, financial advice, personal opinions, medical advice, religion, race, politics, sexuality, gender, or any other non-web-development topics). If asked about these, respond with: "Sorry, I can't answer that. I'm best at questions about web development and debugging."
+* **CRITICAL**: Do not write full Python programs or other scripts to interact with the environment. Only invoke the allowed tools.
+* **CRITICAL**: Do not expose raw, internal system identifiers (such as database IDs, internal node paths, or event keys) directly to the user. Use descriptive names instead.`;
+
 export class AiAgent2 extends AiAgent<unknown> {
   // TODO: The static preamble is a placeholder and will eventually live server-side.
-  readonly preamble = 'You are a unified AI assistant in Chrome DevTools. You can learn skills to help the user.';
-  readonly clientFeature = Host.AidaClient.ClientFeature.CHROME_STYLING_AGENT;  // Placeholder
+  readonly preamble = preamble;
+  readonly clientFeature = Host.AidaClient.ClientFeature.CHROME_DEVTOOLS_V2_AGENT;
   readonly userTier = 'TESTERS';
 
   #skillsInjected = false;
   #changes = new ChangeManager();
   #execJs: typeof executeJsCode;
+  readonly #allowedOrigin?: () => AllowedOriginResult;
 
   get options(): RequestOptions {
     return {};
@@ -46,6 +76,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 +200,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 +210,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/AiConversation.ts

@@ -25,8 +25,8 @@ import {
   type UserQuery
 } from './agents/AiAgent.js';
 import {ContextSelectionAgent} from './agents/ContextSelectionAgent.js';
-import {FileAgent, FileContext} from './agents/FileAgent.js';
-import {NetworkAgent, RequestContext} from './agents/NetworkAgent.js';
+import {FileAgent} from './agents/FileAgent.js';
+import {NetworkAgent} from './agents/NetworkAgent.js';
 import {PerformanceAgent, PerformanceTraceContext} from './agents/PerformanceAgent.js';
 import {StorageAgent, StorageContext} from './agents/StorageAgent.js';
 import {StylingAgent} from './agents/StylingAgent.js';
@@ -34,6 +34,8 @@ import {AiAgent2} from './AiAgent2.js';
 import {AiHistoryStorage, ConversationType, type SerializedConversation} from './AiHistoryStorage.js';
 import type {ChangeManager} from './ChangeManager.js';
 import {DOMNodeContext} from './contexts/DOMNodeContext.js';
+import {FileContext} from './contexts/FileContext.js';
+import {RequestContext} from './contexts/RequestContext.js';
 
 export const NOT_FOUND_IMAGE_DATA = '';
 export const CONTEXT_TITLE = 'Analyzing data';

package/front_end/models/ai_assistance/AiOrigins.ts

@@ -9,6 +9,8 @@ import type * as Platform from '../../core/platform/platform.js';
  * Returns true if the origin is considered opaque and should be blocked from
  * AI assistance to prevent potential data leakage.
  *
+ * @param origin The origin string to check.
+ * @returns True if the origin is opaque and blocked.
  * @see https://crbug.com/513732588
  */
 export function isOpaqueOrigin(origin: string): boolean {
@@ -16,13 +18,22 @@ export function isOpaqueOrigin(origin: string): boolean {
    * Origins starting with 'about' (like about:blank or about:srcdoc) are
    * considered opaque. 'about://' is the sentinel used by DevTools
    * ParsedURL.securityOrigin() for these.
+   *
+   * We also treat empty origins, 'undefined', and 'null' as opaque to prevent
+   * bypasses when URL parsing fails or variables are uninitialized.
    */
-  return origin === 'null' || origin === 'data:' || origin.startsWith('about') || origin.startsWith('detached');
+  const lower = origin.toLowerCase();
+  return lower === '' || lower === 'null' || lower === 'data:' || lower.startsWith('about') ||
+      lower.startsWith('detached') || lower.startsWith('undefined');
 }
 
 /**
  * Extracts the origin from a context URL or identifier.
- * Handles special cases like "detached" nodes and trace identifiers.
+ * Handles special cases like "detached" nodes, trace identifiers,
+ * opaque blob URLs, and isolates local file paths.
+ *
+ * @param contextURL The context URL or trace/node identifier.
+ * @returns The extracted origin string.
  */
 export function extractContextOrigin(contextURL: string): string {
   if (isOpaqueOrigin(contextURL)) {
@@ -31,6 +42,28 @@ export function extractContextOrigin(contextURL: string): string {
   if (contextURL.startsWith('trace-')) {
     return contextURL;
   }
+  // If a blob URL has an opaque inner origin (e.g. blob:null/uuid, blob:about:blank),
+  // it won't contain "://". We classify these as opaque ('null') to prevent cross-origin leaks.
+  if (/^blob:/i.test(contextURL)) {
+    const innerURL = contextURL.substring(5);
+    if (!innerURL.includes('://')) {
+      return 'null';
+    }
+  }
+  // Local files collapse to a generic "file://" origin by default. We isolate them
+  // by appending the normalized path, ensuring distinct files are treated as different origins.
+  if (/^file:\/\//i.test(contextURL)) {
+    const parsed = Common.ParsedURL.ParsedURL.fromString(contextURL as Platform.DevToolsPath.UrlString);
+    if (parsed) {
+      // Include host and port (authority) to preserve server names in Windows UNC paths
+      // (e.g. file://server/path) so different network shares are isolated.
+      const authority = parsed.host + (parsed.port ? ':' + parsed.port : '');
+      return 'file://' + authority + parsed.path;
+    }
+    // Fallback to 'null' (opaque) if parsing fails. This prevents malformed file URLs
+    // from bypassing isolation by collapsing to the same 'file://' string.
+    return 'null';
+  }
   return Common.ParsedURL.ParsedURL.extractOrigin(contextURL as Platform.DevToolsPath.UrlString);
 }
 
@@ -44,3 +77,31 @@ export function areOriginsEquivalent(origin1: string, origin2: string): boolean
   }
   return origin1 === origin2;
 }
+
+/**
+ * Validates if the source code contents of a file (identified by targetURL) can be retrieved
+ * and shared with the AI, based on the origin of the active trace context.
+ *
+ * This function handles the following branches:
+ * 1. **Opaque origins**: If either the trace origin or target file origin is opaque
+ *    (e.g., data URLs, about:blank, sandboxed frames), access is blocked.
+ * 2. **Fresh Recordings**: For live page recordings, a strict same-origin comparison
+ *    (scheme, host, and port matching) is enforced.
+ *
+ * @param targetURL The URL of the file to be read.
+ * @param traceOrigin The allowed origin of the trace context.
+ * @returns true if reading the file is permitted; false otherwise.
+ */
+export function canResourceContentsBeReadForTrace(targetURL: string, traceOrigin: string): boolean {
+  // We explicitly block all file:// URLs. While we want to allow users to debug
+  // traces on local sites, allowing file:// access poses security risks (e.g.,
+  // reading local files like /etc/passwd via prompt injection) because file://
+  // origins are not sufficiently isolated from each other in DevTools' origin model.
+  if (traceOrigin.startsWith('file://') || targetURL.startsWith('file://')) {
+    return false;
+  }
+
+  const targetOrigin = extractContextOrigin(targetURL);
+
+  return areOriginsEquivalent(targetOrigin, traceOrigin);
+}

package/front_end/models/ai_assistance/README.md

@@ -11,12 +11,14 @@ Each agent has a _context_ defined, which represents the selected data that form
 - The `PerformanceAgent` has an individual performance trace and a specific focus (an insight, or a call tree) as its context.
 - The `StylingAgent` has a DOM Node as its context.
 
-When defining a context, they must extend the `ConversationContext` interface, which defines a few methods which must be implemented, including:
+Contexts are defined as subclasses extending the `ConversationContext` abstract class, which defines the following key methods:
 
-- `getOrigin()`: the origin of the data. This is important as for security concerns if the user swaps to a new context with a different origin, a new conversation must be started to avoid any concerns of sharing data across origins.
-- `getTitle()` which are used to represent the context in the UI.
+- `getOrigin()`: the origin of the data. This is critical for security: if the user switches to a new context with a different origin, the panel forces a new conversation to avoid cross-origin data exposure.
+- `getTitle()`: returns the user-facing title of the context.
+- `getPromptDetails()`: returns a Markdown formatted description of the context item to be directly included in the LLM prompt.
+- `getUserFacingDetails()`: returns structured details (such as request/response headers, timings, etc.) displayed to the user in the UI under the "Analyzing data" accordion.
 
-When the user begins a conversation with the AI, we want to include information based on the active context to send as part of the prompt. This is done in the agent implementation by overriding the `enhanceQuery()` method, which takes the active context as the second argument. This method can be used to enrich the query with contextual information.
+Encapsulating prompt formatting and UI generation within the context classes simplifies agent implementations and promotes reusability. Contexts are located in the `contexts/` directory.
 
 ### Formatters
 
@@ -24,7 +26,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 +38,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
 
@@ -101,3 +104,12 @@ To aid debugging, you can enable the AI Assistance logging. This setting is stor
 4. In the console, run `setDebugAiAssistanceEnabled(true)`.
 
 Now, when interacting with the AI and sending requests, you will see output logged to the console. You can use the `debugLog` helper to add your own logging as you are building out your feature.
+
+## Security & Origin Isolation
+
+To prevent prompt injection attacks and cross-origin data leaks, the AI Assistance panel enforces strict origin-lock boundaries:
+
+*   **Origin Locking**: Once a conversation session begins, it locks to the origin of the initial data context (e.g. `https://google.com` or a specific file path).
+*   **Opaque Origins**: Any origin classified as opaque (e.g. `data:`, `about:`, `detached` nodes, unparsed `undefined://` or empty origins) is blocked from starting AI assistance (`isOpaqueOrigin()`).
+*   **File Isolation**: Local files (`file://`) do not share a single wildcard origin. Instead, the path is appended (e.g. `file:///path/to/file.js`) to treat each local file as its own unique origin. Swapping local files in the same conversation is blocked.
+*   **Equivalence**: `areOriginsEquivalent()` ensures opaque origins are never equivalent to anything (including themselves), forcing a conversation reset on transitions.