### Example: Login Task using page.aiAction() (Explicit Steps)

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Shows how to perform the same login task using page.aiAction() by explicitly defining each step.

```typescript
await page.aiAction("click the email field");
await page.aiAction("type 'test@example.com' into the email field");
await page.aiAction("click the password field");
await page.aiAction("type 'pass123' into the password field");
await page.aiAction("click the login button");
```

--------------------------------

### Example: Login Task using page.ai() (Multi-step Agent)

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Demonstrates how page.ai() handles a multi-step task like login autonomously, breaking it down into agent actions.

```typescript
await page.ai("Login with email 'test@example.com' and password 'pass123'");
// Agent executes:
// Step 1: actElement (click email field)
// Step 2: actElement (type 'test@example.com')
// Step 3: actElement (click password field)  
// Step 4: actElement (type 'pass123')
// Step 5: actElement (click login button)
// Step 6: complete
```

--------------------------------

### Build and Development Commands

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/CLAUDE.md

Common commands for building, linting, formatting, testing, and running the CLI or examples. Ensure 'yarn build' is run before publishing.

```bash
yarn build        # Wipe dist/, run tsc + tsc-alias, restore CLI executable bits
yarn lint         # ESLint on src/**/*.ts (flat config)
yarn format       # Prettier on src/**/*.ts
yarn test         # Jest
yarn cli -c "task" [--debug --hyperbrowser --mcp <path>]  # Run agent interactively
yarn example <path>  # Execute a file from examples/ or scripts/ via ts-node
```

--------------------------------

### CDP Synchronization Timeline Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the step-by-step process of synchronizing frame information using CDP events and DOM traversal, highlighting the role of backendNodeId.

```text
Step 1: ensureInitialized() - Attach event listeners
  └─ Page.frameAttached fires → frameId="ABC123"
     └─ Call DOM.getFrameOwner("ABC123") → backendNodeId=99
        └─ Store: { frameId: "ABC123", backendNodeId: 99 }

Step 2: buildBackendIdMaps() - DOM traversal
  └─ DOM.getDocument finds <iframe> → iframeBackendNodeId=99
     └─ Store: frameMap[1] = { iframeBackendNodeId: 99, frameId: undefined }

Step 3: syncFrameContextManager() - Match them!
  └─ frameMap[1].iframeBackendNodeId = 99
     └─ Match with FrameContextManager { frameId: "ABC123", backendNodeId: 99 }
        └─ Copy frameId into frameMap[1] ✅
           └─ Now complete: { frameId: "ABC123", executionContextId: 5, ... }
```

--------------------------------

### Build DOM View Text Representation

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

Example of the text representation of DOM elements, including index, tag, and content, used for agent interaction.

```plaintext
[1]<button id="submit" class="btn-primary">Submit Form</button>
[2]<input type="text" name="email" placeholder="Enter email">
Some text between elements
[3]<a href="/pricing">View Pricing</a>
```

--------------------------------

### Install Hyperagent with npm or yarn

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Use npm or yarn to add the Hyperagent package to your project dependencies.

```bash
# Using npm
npm install @hyperbrowser/agent

# Using yarn
yarn add @hyperbrowser/agent
```

--------------------------------

### Agent Task Initialization Flow

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This diagram illustrates the sequence of operations during agent task initialization, from starting the task to attaching event listeners and managing frame contexts.

```text
┌─────────────────────────────────────────────────────────────────────────┐
│                        Agent Task Starts                                 │
│                    (page.ai() or page.aiAction())                       │
└────────────────────────────────┬────────────────────────────────────────┘
                                 │
                                 ▼
                    ┌────────────────────────┐
                    │ ensureFrameContexts    │
                    │       Ready()          │
                    └───────────┬────────────┘
                                │
                                ▼
                    ┌────────────────────────┐
                    │ Get/Create CDP Client  │
                    │  & FrameContextManager │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ FrameContextManager    │
                    │  .ensureInitialized()  │
                    └───────────┬────────────┘
                                │
                ┌───────────────┼───────────────┐
                ▼               ▼               ▼
    ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
    │ Page.enable  │ │ DOM.enable   │ │Runtime.enable│
    └──────┬───────┘ └──────┬───────┘ └──────┬───────┘
           │                │                │
           ▼                ▼                ▼
    [Attach Event Listeners]
    ═══════════════════════════════════════════════════
    
    • Page.frameAttached         • Page.frameNavigated
    • Page.frameDetached          • Runtime.executionContextCreated
    • Runtime.executionContextDestroyed

    Data Structures Created:
    ═══════════════════════════════════════════════════
    [FrameGraph]                   [sessions Map]
    ├─ frames: Map<frameId, FrameRecord>
    ├─ frameIndexMap: Map<frameIndex, frameId>
    └─ Root frame registered       [frameExecutionContexts Map]
                                   ├─ frameId → contextId
                                   └─ Empty, waiting for events

                                 │
                                 ▼
                    ┌────────────────────────┐
                    │ Page.getFrameTree()    │
                    │  Enumerate existing    │
                    │  frames at start       │
                    └───────────┬────────────┘
                                │
                    ┌───────────▼────────────┐
                    │ For each frame found:  │
                    │ • upsertFrame()        │
                    │ • setFrameSession()    │
                    │ • populateFrameOwner() │ ← Calls DOM.getFrameOwner!
                    │ • Assign frameIndex    │
                    └────────────────────────┘

    AFTER INITIALIZATION - Data State by Frame Type:
    ═══════════════════════════════════════════════════════════════
    
    ℹ️  NOTE: Page.getFrameTree captures ALL frames that exist at load time
    (including same-origin iframes). Page.frameAttached events handle:
    - Dynamically created iframes (added after page load via JavaScript)
    - Race conditions (frames attaching during initialization)
    - Frame navigations (creating new execution contexts)
    
    MAIN FRAME (frameIndex 0):
    ──────────────────────────────
    [FrameGraph]
    { frameId: "ROOT_123",
      backendNodeId: undefined,        ← Main frame has no <iframe> element
      executionContextId: 5 }          ← ✅ Usually available immediately

    SAME-ORIGIN IFRAMES (e.g., frameIndex 1):
    ──────────────────────────────────────────
    [FrameGraph] 
    { frameId: "ABC123",               ← ✅ From Page.getFrameTree (recursive childFrames)
      backendNodeId: 99,               ← ✅ From DOM.getFrameOwner("ABC123")
      executionContextId: undefined }  ← ❌ May still be loading (async)

    OOPIF FRAMES (e.g., frameIndex 3):
    ───────────────────────────────────
    [FrameGraph]
    { frameId: "XYZ789",               ← ✅ Discovered via captureOOPIFs
      backendNodeId: 123,              ← ✅ From DOM.getFrameOwner("XYZ789")
      executionContextId: undefined,   ← ❌ May still be loading
      sessionId: "oopif-session-1" }   ← ✅ Separate CDP session

    NOW READY: Event listeners active, frame manager tracking frames
    NEXT: getA11yDOM() will call buildBackendIdMaps() to get DOM structure
```

--------------------------------

### Example JSON Output for Schema Extraction

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

This is an example of the JSON output structure that can be obtained when using a defined output schema with HyperAgent.

```json
{
  "director": "Lana Wachowski, Lilly Wachowski",
  "releaseYear": 1999,
  "rating": "8.7/10"
}
```

--------------------------------

### Execution Context Collection Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the collection of execution contexts within a browser frame. This is a crucial step before injecting scripts or evaluating expressions in specific contexts.

```javascript
iframeBackendNodeId: 99,
...
}

[frameExecutionContexts Map]
"ABC123" → 5
"DEF456" → 8
"GHI789" → 12
```

--------------------------------

### Output of buildHierarchicalTree

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

An example of the output from `buildHierarchicalTree`, showing the hierarchical accessibility tree, a simplified string representation, and a map of bounding boxes keyed by `encodedId`.

```typescript
{
  tree: [
    {
      role: "button",
      name: "Login",
      backendDOMNodeId: 15,
      encodedId: "0-15"
    },
    {
      role: "textbox",
      name: "Email",
      backendDOMNodeId: 23,
      encodedId: "0-23"
    }
  ],
  simplified: `
[0-15] button "Login"
[0-23] textbox "Email"

Frame 1 (https://example.com/child.html):
[1-42] button "I'm in an iframe"
[1-43] textbox "Password"
  `,
  boundingBoxMap: Map {
    "0-15" => { x: 100, y: 200, width: 80, height: 40, ... },
    "0-23" => { x: 100, y: 250, width: 200, height: 30, ... },
    "1-42" => { x: 50, y: 500, width: 100, height: 35, ... }, 
  }
}
```

--------------------------------

### DOM Traversal Output Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This output shows the logs generated during a DOM tree traversal by `buildBackendIdMaps()`. It details detected frames, including same-origin iframes, and provides statistics on DOM nodes and input elements per frame. Note that OOPIF frames are discovered separately.

```text
[DOM] Same-origin iframe without frameId (expected) - will match by backendNodeId=123
[DOM] Iframe detected: frameIndex=1, parent=0, iframeBackendNodeId=123, contentDocBackendNodeId=456, cdpFrameId="undefined", src="https://example.com/frame1.html", siblingPos=0

[DOM.getDocument] DOM tree statistics:
  Frame 0 (https://example.com): 1247 DOM nodes, 15 input/textarea elements
  Frame 1 (https://example.com/frame1.html): 89 DOM nodes, 3 input/textarea elements
```

--------------------------------

### Using Variables in Actions

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

This example shows how variables are used within agent actions, specifically in the 'inputText' action where placeholders like '<<variable.key>>' are replaced with their corresponding values.

```typescript
// In inputText action:
text = text.replace(`<<${variable.key}>>`, variable.value);
// Agent can use: inputText(5, "<<email>>") → "user@example.com"
```

--------------------------------

### DOM.getDocument Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the data obtained from calling DOM.getDocument with pierce: true, highlighting what information is available for same-origin iframes and what is missing, such as frameId and executionContextId.

```typescript
// Time T=0: Page with same-origin iframe and OOPIF
await page.goto("https://example.com");

// Time T=100ms: We call DOM.getDocument
const { root } = await session.send("DOM.getDocument", { pierce: true });

// What we GET:
// ✅ <iframe> tag for same-origin iframe (backendNodeId: 99)
// ✅ contentDocument for same-origin iframe (backendNodeId: 100)
// ✅ All elements inside same-origin iframe
// ❌ NO frameId for the iframe
// ❌ NO executionContextId for any frame
// ❌ OOPIF iframe is COMPLETELY MISSING (cross-origin blocked)

// Our frameMap after DOM traversal:
{
  frameIndex: 1,
  iframeBackendNodeId: 99,           // ✅ We have this
  contentDocumentBackendNodeId: 100,  // ✅ We have this
  frameId: undefined,                 // ❌ Missing!
  executionContextId: undefined       // ❌ Missing!
}

// OOPIFs don't even appear in the traversal!
```

--------------------------------

### Build A11y DOM Maps with CDP

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This example demonstrates fetching the entire DOM tree, including iframe contents, and then retrieving box model information for iframes. It's used to build backend ID maps for accessibility.

```typescript
const { root } = await session.send("DOM.getDocument", {
  depth: -1,    // Unlimited depth
  pierce: true  // Include iframe contents (for main frame)
});

// For each iframe found, get its bounding box
const boxModel = await session.send("DOM.getBoxModel", {
  backendNodeId: iframeBackendNodeId
});
```

--------------------------------

### Initialize Frame Tracking with ensureInitialized()

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Ensures the frame tracking system is initialized by capturing existing frames and attaching event listeners for future frames. Call this once at the start of your session.

```typescript
async ensureInitialized(): Promise<void> {
  if (this.initialized) return;
  
  // Step 1a: Capture frames that exist at page load
  await this.captureFrameTree(rootSession);
  
  // Step 1b: Attach event listeners for frames that load LATER
  await this.trackPageEvents(rootSession);
  
  this.initialized = true;
}
```

--------------------------------

### Frame Context Manager State Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This JSON structure represents the state of the FrameContextManager after initialization. It maps frame IDs to their properties, including URL, session information, and backend node IDs. It highlights how different frame types (main, same-origin, OOPIF) are managed and assigned sessions.

```json
{
  "graph": {
    "frames": {
      "E8F7A9B2C1D3E4F5": {
        "frameId": "E8F7A9B2C1D3E4F5",
        "frameIndex": 1,
        "parentFrameId": "ROOT_FRAME_ID",
        "url": "https://example.com/frame1.html",
        "name": "content-frame",
        "sessionId": "CDP-Session-1",
        "backendNodeId": 123,
        "lastUpdated": 1731782400000
      },
      "F9G8H7I6J5K4L3M2": {
        "frameId": "F9G8H7I6J5K4L3M2",
        "frameIndex": 2,
        "parentFrameId": "ROOT_FRAME_ID",
        "url": "https://ads.example.com/ad.html",
        "name": null,
        "sessionId": "CDP-Session-2",
        "backendNodeId": 789,
        "lastUpdated": 1731782401000
      }
    },
    "frameIndexMap": {
      "0": "ROOT_FRAME_ID",
      "1": "E8F7A9B2C1D3E4F5",
      "2": "F9G8H7I6J5K4L3M2"
    }
  }
}
```

--------------------------------

### Backend Node Map Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the mapping between stable encoded IDs and Chrome's backendNodeIds. This map is crucial for interacting with DOM elements via CDP.

```typescript
{
  "0-15": 15,   // Main frame button
  "1-42": 42,   // Iframe button  
  "1-43": 43,   // Iframe input field
}
```

--------------------------------

### Initialize HyperAgent and execute a task

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Demonstrates initializing the HyperAgent with an LLM provider and executing a complex task involving navigation, searching, and data extraction.

```typescript
import { HyperAgent } from "@hyperbrowser/agent";
import { z } from "zod";

// Initialize the agent
const agent = new HyperAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
  },
});

// Execute a task
const result = await agent.executeTask(
  "Navigate to amazon.com, search for 'laptop', and extract the prices of the first 5 results"
);
console.log(result.output);

// Use page.ai, page.perform, and page.extract
const page = await agent.newPage();
await page.goto("https://flights.google.com", { waitUntil: "load" });
await page.ai("search for flights from Rio to LAX from July 16 to July 22");
await page.perform("click the search button");
const res = await page.extract(
  "give me the flight options",
  z.object({
    flights: z.array(
      z.object({
        price: z.number(),
        departure: z.string(),
        arrival: z.string(),
      })
    ),
  })
);
console.log(res);

// Clean up
await agent.closeAgent();
```

--------------------------------

### Initialize MCP Client

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

Connect external tools as custom actions by initializing the MCP client with server configurations.

```typescript
await agent.initializeMCPClient({
  servers: [{
    id: "filesystem",
    command: "npx",
    args: ["-y", "@modelcontextprotocol/server-filesystem"]
  }]
});
```

--------------------------------

### Workflow 1: Clicking an Element

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

Illustrates the step-by-step process of initiating a click action through the AI interface.

```APIDOC
## Workflow 1: `page.ai("click the login button")`

1. User calls `page.ai("click the login button")`.
2. The system calls `agent.executeTask(task, params, page)`.
3. `runAgentTask()` initiates the task loop.
4. `getDom(page)` is called to extract DOM information and a screenshot, including injecting JavaScript to find interactive elements, drawing overlays, and compositing the screenshot.
5. `buildAgentStepMessages()` constructs the prompt for the LLM.
6. `llm.invokeStructured()` is used to obtain an action plan from the LLM.
7. Actions are executed based on the LLM's plan. For example, the LLM might return `{ type: "clickElement", params: { index: 5 } }`.
8. `runAction()` is called, which in turn calls `ClickElementActionDefinition.run()`.
9. The system retrieves the locator for the specified element index (e.g., 5) and performs the click using Playwright.
10. The loop repeats for the next action or the task is marked as complete.
```

--------------------------------

### Initialize MCP Client and Execute Task

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Initializes an MCP client to interact with external services like Google Sheets via a specified server. It then executes a task that involves web scraping and data insertion.

```typescript
const agent = new HyperAgent({
  llm: llm,
  debug: true,
});

await agent.initializeMCPClient({
  servers: [
    {
      command: "npx",
      args: [
        "@composio/mcp@latest",
        "start",
        "--url",
        "https://mcp.composio.dev/googlesheets/...",
      ],
      env: {
        npm_config_yes: "true",
      },
    },
  ],
});

const response = await agent.executeTask(
  "Go to https://en.wikipedia.org/wiki/List_of_U.S._states_and_territories_by_population and get the data on the top 5 most populous states from the table. Then insert that data into a google sheet. You may need to first check if there is an active connection to google sheet, and if there isn't connect to it and present me with the link to sign in. "
);

console.log(response);
await agent.closeAgent();
```

--------------------------------

### Simulate Element Click with CDP

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Performs a click action on an element using CDP. Requires scrolling, getting the box model, and dispatching mouse events.

```typescript
// 1. Scroll into view
await session.send("DOM.scrollIntoViewIfNeeded", {
  backendNodeId: 42
});

// 2. Get bounding box
const { model } = await session.send("DOM.getBoxModel", {
  backendNodeId: 42
});
// model.border = [x1, y1, x2, y2, x3, y3, x4, y4] (quad)

// 3. Compute center point
const x = 150;  // Center of bounding box
const y = 225;

// 4. Move mouse
await session.send("Input.dispatchMouseEvent", {
  type: "mouseMoved",
  x: 150,
  y: 225
});

// 5. Press mouse button
await session.send("Input.dispatchMouseEvent", {
  type: "mousePressed",
  x: 150,
  y: 225,
  button: "left",  // or "right" for context menu
  clickCount: 1    // or 2 for double-click
});

// 6. Release mouse button
await session.send("Input.dispatchMouseEvent", {
  type: "mouseReleased",
  x: 150,
  y: 225,
  button: "left",
  clickCount: 1
});
```

--------------------------------

### Get Playwright Locator from DOM State

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

Retrieves a Playwright Locator for an element based on its index in the current DOM state. Returns null if the element is not found.

```typescript
export const getLocator = (ctx: ActionContext, index: number): Locator | null => {
  const element = ctx.domState.elements.get(index);
  if (!element) return null;
  return ctx.page.locator(element.cssPath);  // Use CSS path selector
};
```

--------------------------------

### Running Integration Tests

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/CLAUDE.md

How to execute integration and smoke tests located in the scripts/ directory. These tests cover various functionalities like page AI and async operations.

```bash
yarn example scripts/test-page-ai.ts
```

--------------------------------

### CDP Initialization and Frame Discovery

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the initial CDP calls like Page.getFrameTree and Runtime.executionContextCreated during initialization. Preliminary frameIndex assignments are made based on traversal, but these are subject to change.

```javascript
Page.getFrameTree()
  → enumerate existing frames
  ├─ Root: { id: "ROOT", parentId: null }
  │  └─ Assigns preliminary frameIndex=0
  ├─ Child: { id: "E8F7A9B2C1D3E4F5", parentId: "ROOT" }
  │  └─ Assigns preliminary frameIndex=1
  └─ Registers frames in FrameGraph

Page.frameNavigated (for each frame)
  { frame: { id: "E8F7A9B2C1D3E4F5", url: "/frame1.html" } }
  → Updates URL in FrameGraph

Runtime.executionContextCreated
  { context: { id: 5, auxData: { frameId: "E8F7A9B2C1D3E4F5" } } }
  → frameExecutionContexts.set("E8F7A9B2C1D3E4F5", 5)
```

--------------------------------

### Configure Cloud Headless Browsers with Hyperbrowser

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

To use cloud headless browsers, obtain an API key from Hyperbrowser, set it as the `HYPERBROWSER_API_KEY` environment variable, and configure `browserProvider` to 'Hyperbrowser'.

```typescript
const agent = new HyperAgent({
  browserProvider: "Hyperbrowser",
});

const response = await agent.executeTask(
  "Go to hackernews, and list me the 5 most recent article titles"
);

console.log(response);
await agent.closeAgent();
```

--------------------------------

### Available Actions

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

A list of all available actions the agent can perform, along with their purpose and key parameters.

```APIDOC
## Available Actions

| Action | Purpose | Key Parameters | Location |
|---|---|---|---|
| `clickElement` | Click an element | `index: number` | [click-element.ts](src/agent/actions/click-element.ts) |
| `inputText` | Fill input field | `index: number, text: string` | [input-text.ts](src/agent/actions/input-text.ts) |
| `extract` | Extract data | `objective: string` | [extract.ts](src/agent/actions/extract.ts) |
| `goToUrl` | Navigate to URL | `url: string` | [go-to-url.ts](src/agent/actions/go-to-url.ts) |
| `selectOption` | Select dropdown | `index: number, option: string` | [select-option.ts](src/agent/actions/select-option.ts) |
| `scroll` | Scroll page | `direction: "up"|"down"` | [scroll.ts](src/agent/actions/scroll.ts) |
| `keyPress` | Press keyboard key | `key: string` | [key-press.ts](src/agent/actions/key-press.ts) |
| `complete` | End task | `output?: string` | [complete.ts](src/agent/actions/complete.ts) |
```

--------------------------------

### Frame Index Assignment Logic

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates how `frameIndex` is assigned during DFS traversal, starting from 1. It emphasizes that `frameIndex` reflects DOM document order, not CDP event order.

```javascript
let nextFrameIndex = frameIndex + 1; // Start at 1

When an <iframe> is discovered:
  const iframeFrameIndex = nextFrameIndex++;
  frameMap.set(iframeFrameIndex, IframeInfo)
```

--------------------------------

### XPath Map Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Stores XPath expressions to reliably locate elements when backendNodeIds become stale due to DOM mutations or navigation. XPaths are relative to their respective frame documents.

```typescript
{
  "0-15": "//html[1]/body[1]/button[1]",
  "1-42": "//button[1]",  // Relative to iframe document!
  "1-43": "//input[1]"
}
```

--------------------------------

### HyperAgent Variable Management API

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/currentState.md

This TypeScript interface defines the structure for HyperAgent variables, which consist of a key, value, and optional description. The API allows adding, getting, and deleting these variables.

```typescript
interface HyperVariable {
  key: string;
  value: string;
  description?: string;
}

// API
agent.addVariable({ key: "email", value: "user@example.com" })
agent.getVariable("email")
agent.deleteVariable("email")
```

--------------------------------

### Run a task using Hyperagent CLI

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Execute a natural language command directly from the command line using the Hyperagent CLI.

```bash
$ npx @hyperbrowser/agent -c "Find a route from Miami to New Orleans, and provide the detailed route information."
```

--------------------------------

### Capture OOPIF Frames Without Piercing

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

When called on an OOPIF session with `pierce: false`, this function avoids capturing nested iframes. This prevents issues with transitional states and avoids processing frames that will get their own sessions.

```typescript
// Called on OOPIF session - we DON'T want to pierce nested iframes
const subMaps = await buildBackendIdMaps(oopifSession, frameIndex, debug, false);
```

--------------------------------

### pressKey(ctx, key)

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Simulates pressing a keyboard key, including key down and key up events. It uses the `Input.dispatchKeyEvent` CDP command.

```APIDOC
## pressKey(ctx, key)

### Description
Simulates pressing a keyboard key, including key down and key up events. It uses the `Input.dispatchKeyEvent` CDP command.

### Method
`Input.dispatchKeyEvent`

### Parameters
#### Key Down Event Parameters
- **type** (string) - Required - Set to `"keyDown"`.
- **key** (string) - Required - The key identifier (e.g., `"Enter"`, `"Escape"`).
- **code** (string) - Required - The physical key code (e.g., `"Enter"`).
- **text** (string) - Optional - Text produced by the key press (e.g., `"\r"` for Enter).
- **windowsVirtualKeyCode** (number) - Optional - Windows virtual key code.
- **nativeVirtualKeyCode** (number) - Optional - Native virtual key code.

#### Key Up Event Parameters
- **type** (string) - Required - Set to `"keyUp"`.
- **key** (string) - Required - The key identifier (e.g., `"Enter"`).
- **code** (string) - Required - The physical key code (e.g., `"Enter"`).
- **windowsVirtualKeyCode** (number) - Optional - Windows virtual key code.
- **nativeVirtualKeyCode** (number) - Optional - Native virtual key code.

### Request Example (Pressing Enter)
```typescript
// Key down
await session.send("Input.dispatchKeyEvent", {
  type: "keyDown",
  key: "Enter",
  code: "Enter",
  text: "\r",
  windowsVirtualKeyCode: 13,
  nativeVirtualKeyCode: 13
});

// Key up
await session.send("Input.dispatchKeyEvent", {
  type: "keyUp",
  key: "Enter",
  code: "Enter",
  windowsVirtualKeyCode: 13,
  nativeVirtualKeyCode: 13
});
```

### Common Keys:
- `"Enter"` → Submit forms
- `"Escape"` → Close modals
- `"Tab"` → Navigate between fields
- `"ArrowDown"` → Open dropdown menus
```

--------------------------------

### Accessibility Tree with Encoded IDs Example

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This TypeScript Map represents an accessibility tree where each element is identified by an `encodedId`. The `encodedId` format (e.g., 'frameIndex-backendNodeId') helps distinguish elements across different frames, including the main frame, same-origin frames, and out-of-process iframes (OOPIFs).

```typescript
Map {
  "0-45" => {
    role: "button",
    name: "Login",
    backendDOMNodeId: 45,
    nodeId: "ax-129",
    encodedId: "0-45",
    boundingBox: { x: 100, y: 200, width: 80, height: 40, ... }
  },
  "1-23" => {
    role: "textbox",
    name: "Email",
    value: "",
    backendDOMNodeId: 23,
    nodeId: "ax-456",
    encodedId: "1-23",
    boundingBox: { x: 50, y: 350, width: 200, height: 30, ... }
  },
  "2-67" => {
    role: "link",
    name: "Click Here for Deals",
    backendDOMNodeId: 67,
    nodeId: "ax-789",
    encodedId: "2-67"
  }
}
```

--------------------------------

### Critical Sequence for Frame Synchronization

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the sequence of operations: initializing the frame context, building backend ID maps via DOM traversal, and finally synchronizing the context manager with the frame map using backendNodeId as the bridge.

```text
1. ensureInitialized()
   ├─ Page.getFrameTree → frameId for existing frames
   ├─ DOM.getFrameOwner(frameId) → backendNodeId (THE LINK!)
   └─ Attach Page.frameAttached listener → frameId for async frames
                                         └─ Also calls DOM.getFrameOwner

2. buildBackendIdMaps()
   └─ DOM.getDocument({ pierce: true })
      ├─ Finds <iframe> tags → iframeBackendNodeId
      ├─ Gets contentDocument → iframe content  
      └─ NO frameId in response ❌

3. syncFrameContextManager()
   └─ Match by backendNodeId (the shared key!)
      ├─ frameMap[1].iframeBackendNodeId = 99
      ├─ FrameContextManager has { frameId: "ABC", backendNodeId: 99 }
      └─ frameMap[1].frameId = "ABC" ✅
         frameMap[1].executionContextId = 5 ✅
```

--------------------------------

### Environment Variables for LLM Providers and Features

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/CLAUDE.md

Configuration of various LLM providers and feature flags using environment variables. The OpenAI provider is the default if no other LLM is explicitly configured.

```bash
OPENAI_API_KEY
ANTHROPIC_API_KEY
GEMINI_API_KEY / GOOGLE_API_KEY
DEEPSEEK_API_KEY
HYPERBROWSER_API_KEY
HYPERAGENT_TRACE_WAIT
HYPERAGENT_PROFILE_DOM
HYPERAGENT_DEBUG_STRUCTURED_SCHEMA
```

--------------------------------

### CDP State Synchronization Diagram

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the flow of data and synchronization between static maps, dynamic state, and element resolution using CDP events.

```text
┌─────────────────────────────────────────────────────────────┐
│                    Static Maps (Point-in-time)              │
├─────────────────────────────────────────────────────────────┤
│ backendNodeMap: { "1-23": 23, "1-24": 24, ... }           │
│ xpathMap: { "1-23": "//button[1]", ... }                  │
│ frameMap: Map { 1 => { frameId, iframeBackendNodeId } }   │
└─────────────────────────────────────────────────────────────┘
                            ↓ Synced via ↓
┌─────────────────────────────────────────────────────────────┐
│              Dynamic State (Event-driven)                   │
├─────────────────────────────────────────────────────────────┤
│ FrameGraph: { frameId ↔ frameIndex, hierarchy }           │
│ sessions: Map { frameId → CDPSession }                     │
│ frameExecutionContexts: Map { frameId → contextId }        │
│                                                             │
│ Updated by:                                                 │
│ - Page.frameAttached/Detached/Navigated                   │
│ - Runtime.executionContextCreated/Destroyed                │
└─────────────────────────────────────────────────────────────┘
                            ↓ Used by ↓
┌─────────────────────────────────────────────────────────────┐
│                  Element Resolution                         │
├─────────────────────────────────────────────────────────────┤
│ resolveElement("1-23") → {
  session: CDPSession (from sessions map),
  frameId: "ABC123" (from frameGraph),
  backendNodeId: 23 (from backendNodeMap),
  executionContextId: 5 (from frameExecutionContexts)      │
}                                                           │
└─────────────────────────────────────────────────────────────┘
```

--------------------------------

### Data Flow for Element Interaction via CDP

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This sequence illustrates the detailed steps involved when an agent processes an LLM instruction to click an element within an iframe, including DOM traversal, map population, and CDP command dispatch.

```text
1. [LLM Input] "click the button in the iframe"
   ↓
2. [findElementWithRetry] Call getA11yDOM() to build element tree
   ↓
3. [getA11yDOM] 
   - buildBackendIdMaps(): Walk DOM via CDP, create:
     * backendNodeMap: { "1-42": 42 }
     * xpathMap: { "1-42": "//button[1]" }
     * frameMap: Map { 1 => { iframeBackendNodeId: 99, frameId: undefined } }
   - syncFrameContextManager(): Match via backendNodeId, populate:
     * frameMap[1].frameId = "ABC123" ✅
     * frameMap[1].executionContextId = 5 ✅
   - fetchIframeAXTrees(): Get accessibility trees for each frame
   - buildHierarchicalTree(): Merge AX + DOM data, create:
     * elements: Map { "1-42": { role: "button", name: "I\'m in an iframe" } }
   ↓
4. [LLM] Analyze `elements` map, return:
   { elementId: "1-42", method: "click", arguments: [] }
   ↓
5. [executeSingleAction] Parse encodedId "1-42" → frameIndex = 1
   ↓
6. [resolveElement]
   - frameIndex=1 → frameMap.get(1) → frameId="ABC123"
   - FrameContextManager.getFrameSession("ABC123") → CDP session
   - FrameContextManager.getExecutionContextId("ABC123") → contextId=5
   - backendNodeMap["1-42"] → backendNodeId=42
   ↓
7. [dispatchCDPAction("click")]
   - Send CDP command: DOM.scrollIntoViewIfNeeded({ backendNodeId: 42 })
   - Send CDP command: Input.dispatchMouseEvent({ type: "mouseMoved", x: 400, y: 500 })
   - Send CDP command: Input.dispatchMouseEvent({ type: "mousePressed", button: "left" })
   - Send CDP command: Input.dispatchMouseEvent({ type: "mouseReleased", button: "left" })
```

--------------------------------

### Combine page.perform(), page.ai(), and page.extract()

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Combine `perform` for individual actions, `ai()` for complex workflows, and `extract()` for structured data retrieval. Ensure `zod` is imported for schema definition.

```typescript
// Use perform for fast, reliable individual actions
await page.perform("click the search button");
await page.perform("type laptop into search");

// Use ai() for complex, multi-step workflows
await page.ai("filter results by price under $1000 and sort by rating");

// Extract structured data
const products = await page.extract(
  "get the top 5 products",
  z.object({
    products: z.array(z.object({ name: z.string(), price: z.number() }))
  })
);
```

--------------------------------

### Perform single granular actions with page.perform()

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Utilize the `page.perform()` method for fast, reliable, and cost-effective single actions like filling forms or clicking buttons. This method uses the accessibility tree and a single LLM call per action.

```typescript
const page = await agent.newPage();
await page.goto("https://example.com/login");

// Fast, reliable single actions
await page.perform("fill email with user@example.com");
await page.perform("fill password with mypassword");
await page.perform("click the login button");
```

--------------------------------

### Fetch Accessibility Trees with CDP

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Fetches the accessibility tree for the main frame using Accessibility.getFullAXTree and for iframes using Accessibility.getPartialAXTree. Requires frame information from a previous step.

```typescript
const mainAXTree = await session.send("Accessibility.getFullAXTree");
```

```typescript
const iframeAXTree = await session.send("Accessibility.getPartialAXTree", {
  backendNodeId: frameInfo.contentDocumentBackendNodeId
});
```

--------------------------------

### Manage Multiple Pages with HyperAgent

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Create and manage multiple browser pages using `agent.newPage()`. Execute tasks on specific pages and retrieve all active pages with `agent.getPages()`.

```typescript
// Create and manage multiple pages
const page1 = await agent.newPage();
const page2 = await agent.newPage();

// Execute tasks on specific pages
const page1Response = await page1.ai(
  "Go to google.com/travel/explore and set the starting location to New York. Then, return to me the first recommended destination that shows up. Return to me only the name of the location."
);
const page2Response = await page2.ai(
  `I want to plan a trip to ${page1Response.output}. Recommend me places to visit there.`
);

console.log(page2Response.output);

// Get all active pages
const pages = await agent.getPages();
await agent.closeAgent();
```

--------------------------------

### LLM Interaction with DOM State

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the data flow for LLM interaction, showing what the LLM receives and what it returns for element interaction.

```json
LLM receives:
• simplified tree
• screenshot (if visual mode)

LLM returns:
{ elementId: "1-42",
  method: "click",
  arguments: [] }
```

--------------------------------

### Code Flow for page.aiAction()

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Outlines the process for `page.aiAction()`, which handles single, granular actions using a text-based accessibility tree and fewer LLM calls.

```typescript
page.aiAction("click the login button")
  ↓
HyperAgent.executeSingleAction(instruction, page, params)
  ↓
findElementWithRetry(instruction, page, llm, options)
  ↓
Loop up to 10 retries:
  1. getA11yDOM(page, { mode: "a11y" })
     - Builds all maps (same as page.ai)
     - NO screenshot
     - NO bounding boxes
     - Returns text-only accessibility tree
  2. buildExamineDomMessages(domState.simplified, instruction)
     - Formats accessibility tree for LLM
     - Prompt: "Find the element matching: 'click the login button'"
  3. llm.invokeStructured(messages, ExamineDomSchema)
     - LLM identifies element
     - Returns: { elementId: "0-45", method: "click", arguments: [] }
  4. If element found:
     - resolveElement("0-45") using CDP
     - dispatchCDPAction("click", ...)
     - waitForSettledDOM(page)
     - Return success
  5. If not found:
     - Retry with fresh DOM capture (page may have changed)
```

--------------------------------

### Frame Type-Specific Context Handling

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Summarizes context availability and potential initialization delays for different frame types: Main Frame, Same-Origin Iframe, Nested Same-Origin Iframe, and Out-of-Process Iframes (OOPIFs).

```plaintext
Main Frame (index=0):
────────────────────────────────────────
Context usually available immediately
Events tracked on root session
✅ High success rate

Same-Origin Iframe (index=1):
────────────────────────────────────────
Shares root session with main frame
Context created after iframe loads
⚠️  May need short wait (~100ms)

Nested Same-Origin Iframe (index=2):
────────────────────────────────────────
Also on root session
Context created after parent + child load
⚠️  May need wait (~200ms)

OOPIF (index=3):
────────────────────────────────────────
Separate CDP session
Context on OOPIF session, not root
⚠️  Requires captureOOPIFs() first
⏳ May take longer to initialize
```

--------------------------------

### Configure Different LLM Providers

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/README.md

Hyperagent supports multiple LLM providers including OpenAI, Anthropic, Google Gemini, and DeepSeek. Configure the desired provider and model in the `llm` option.

```typescript
// Using OpenAI
const agent = new HyperAgent({
  llm: {
    provider: "openai",
    model: "gpt-4o",
  },
});

// Using Anthropic's Claude
const agent = new HyperAgent({
  llm: {
    provider: "anthropic",
    model: "claude-sonnet-4-0",
  },
});

// Using Google Gemini
const agent = new HyperAgent({
  llm: {
    provider: "gemini",
    model: "gemini-2.5-flash",
  },
});

// Using DeepSeek
const agent = new HyperAgent({
  llm: {
    provider: "deepseek",
    model: "deepseek-chat",
  },
});
```

--------------------------------

### Configure getA11yDOM for page.ai()

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

This configuration is used by page.ai() and includes screenshot and bounding box data for visual debugging.

```typescript
await getA11yDOM(page, {
  mode: "visual-debug",        // Screenshot + bounding boxes
  drawBoundingBoxes: true,     // Visual overlay
  debugDir: "debug/uuid/step-1",
  debug: true
});
```

--------------------------------

### Frame Context Synchronization Logic

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Illustrates the matching logic for synchronizing DOM-discovered frames with event-tracked frames using frameId, backendNodeId, or Playwright frame identifiers. It shows how context IDs are copied and assigned.

```plaintext
SAME-ORIGIN IFRAME (frameIndex 1):
───────────────────────────────────── 
frameMap[1]:
  { iframeBackendNodeId: 99,  ← Primary matching key! 
    frameId: undefined }

FrameContextManager.getFrameByBackendNodeId(99):
  { frameId: "ABC123", backendNodeId: 99 }  ← Match!  

TWO-WAY DATA COPY:
────────────────────                                  
FrameContextManager → frameMap[1]:                    
  frameMap[1].frameId = "ABC123"  ✅                  
  frameMap[1].executionContextId = 5  ✅              

frameMap[1] → FrameContextManager:
  manager.assignFrameIndex("ABC123", 1)  ✅           
  (Overwrites with DOM traversal order)               
```

--------------------------------

### CDP Initialization and Runtime Event Handling

Source: https://github.com/hyperbrowserai/hyperagent/blob/main/docs/cdp-overview.md

Ensures CDP event listeners are attached before capturing the initial state. Runtime events are then used to keep frame and execution context data synchronized.

```typescript
// ========== INITIALIZATION //
// 1. Attach event listeners FIRST
await frameContextManager.ensureInitialized();
// - Listens to Page.frameAttached/Detached/Navigated
// - Listens to Runtime.executionContextCreated/Destroyed

// 2. THEN capture current state
const backendMaps = await buildBackendIdMaps(session);
// - Walks DOM tree (point-in-time snapshot)
// - Creates frameMap, backendNodeMap, xpathMap

// 3. Sync the two views
await syncFrameContextManager(frameContextManager, backendMaps.frameMap);
// - Matches DOM-discovered frames to CDP-tracked frames
// - Uses backendNodeId as the shared key

// ========== RUNTIME //
// 4. Events keep us updated
// When iframe navigates:
Page.frameNavigated event → Updates frameRecord.url
Runtime.executionContextCreated event → Updates frameExecutionContexts[frameId]

// 5. Element resolution uses latest data
const resolved = await resolveElement("1-23", context);
// - frameIndex=1 → looks up latest frameId from frameGraph
// - frameId → looks up latest executionContextId from frameExecutionContexts
// - Always uses current data, not stale snapshot
```