agent-web-interface 4.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Nadeem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,226 @@
+# Agent Web Interface
+
+An MCP server for browser automation that exposes semantic, token-efficient page representations optimized for LLM agents.
+
+---
+
+## Motivation
+
+LLM-based agents operate under strict context window and token constraints.
+However, most browser automation tools expose entire DOMs or full accessibility trees to the model.
+
+This leads to:
+
+- Rapid token exhaustion
+- Higher inference costs
+- Reduced reliability as relevant signal is buried in noise
+
+In practice, agents spend more effort _finding_ the right information than reasoning about it.
+
+Agent Web Interface exists to change the unit of information exposed to the model.
+
+---
+
+## Core Idea: Semantic Page Snapshots
+
+Instead of exposing raw DOM structures or full accessibility trees, Agent Web Interface produces **semantic page snapshots**.
+
+These snapshots are:
+
+- Compact and structured
+- Focused on user-visible intent
+- Designed for LLM recall and reasoning, not DOM completeness
+- Stable across layout shifts and DOM churn
+
+The goal is not to mirror the browser, but to present the page in a form that aligns with how language models reason about interfaces.
+
+---
+
+## How It Works
+
+At a high level:
+
+1. The browser is controlled via Puppeteer and CDP
+2. The page is reduced into semantic regions and actionable elements
+3. A structured snapshot is generated and sent to the LLM
+4. Actions are resolved against stable semantic identifiers rather than fragile selectors
+
+This separation keeps:
+
+- Browser lifecycle management isolated
+- Snapshots deterministic and low-entropy
+- Agent reasoning predictable and efficient
+
+---
+
+## Benchmarks
+
+Early benchmarks against Playwright MCP show:
+
+- **~19% fewer tokens consumed**
+- **~33% faster task completion**
+- Same or better success rates on common navigation tasks
+
+Benchmarks were run using Claude Code on representative real-world tasks.
+Results are task-dependent and should be treated as directional rather than absolute.
+
+---
+
+## What Agent Web Interface Is (and Is Not)
+
+### Agent Web Interface is:
+
+- A semantic interface between browsers and LLM agents
+- An MCP server focused on reliability and efficiency
+- Designed for agent workflows, not test automation
+
+### Agent Web Interface is not:
+
+- A general-purpose browser
+- A visual testing or screenshot framework
+- A replacement for Puppeteer
+
+Puppeteer remains the execution layer; Agent Web Interface focuses on representation and reasoning.
+
+---
+
+## Usage
+
+Agent Web Interface implements the **Model Context Protocol (MCP)** and works with:
+
+- Claude Code
+- Claude Desktop
+- Cursor
+- VS Code
+- Any MCP-compatible client
+
+Example workflows include:
+
+- Navigating complex web apps
+- Handling login and consent flows
+- Performing multi-step UI interactions with lower token usage
+
+See the `examples/` directory for concrete agent workflows.
+
+---
+
+## Claude Code
+
+```bash
+# Basic (auto-launches browser)
+claude mcp add agent-web-interface -- npx agent-web-interface@latest
+
+# With auto-connect to your Chrome profile
+claude mcp add agent-web-interface -- npx agent-web-interface@latest --autoConnect
+
+# Headless mode
+claude mcp add agent-web-interface -- npx agent-web-interface@latest --headless
+```
+
+---
+
+## CLI Arguments
+
+The server accepts the following arguments to configure browser initialization:
+
+| Argument                 | Description                                                     | Default          |
+| ------------------------ | --------------------------------------------------------------- | ---------------- |
+| `--headless=true\|false` | Run browser in headless mode                                    | `false`          |
+| `--browserUrl`           | HTTP endpoint to connect to existing browser                    | -                |
+| `--wsEndpoint`           | WebSocket endpoint to connect to existing browser               | -                |
+| `--autoConnect`          | Auto-connect to Chrome 144+ via DevToolsActivePort              | `false`          |
+| `--isolated`             | Use isolated temp profile instead of persistent                 | `false`          |
+| `--userDataDir`          | Chrome user data directory                                      | Platform default |
+| `--channel`              | Chrome channel (chrome, chrome-canary, chrome-beta, chrome-dev) | `chrome`         |
+| `--executablePath`       | Path to Chrome executable                                       | -                |
+
+### Automatic Browser Initialization
+
+The browser is automatically launched or connected on the first tool call. No explicit initialization is needed.
+
+Examples:
+
+```bash
+# Auto-launch visible browser (default)
+npx agent-web-interface
+
+# Launch headless browser
+npx agent-web-interface --headless
+
+# Auto-connect to Chrome with remote debugging enabled
+npx agent-web-interface --autoConnect
+
+# Connect to specific endpoint
+npx agent-web-interface --browserUrl http://localhost:9222
+```
+
+---
+
+## Using Your Existing Chrome Profile (Chrome 144+)
+
+To connect with your bookmarks, extensions, and logged-in sessions:
+
+1. Navigate to `chrome://inspect/#remote-debugging` in Chrome
+2. Enable remote debugging and allow the connection
+3. Use `--autoConnect` CLI argument
+
+```json
+{
+  "mcpServers": {
+    "agent-web-interface": {
+      "command": "npx",
+      "args": ["agent-web-interface@latest", "--autoConnect"]
+    }
+  }
+}
+```
+
+---
+
+## Environment Variables
+
+| Variable           | Description                                        | Default     |
+| ------------------ | -------------------------------------------------- | ----------- |
+| `AWI_TRIM_REGIONS` | Set to `false` to disable region trimming globally | `true`      |
+| `CEF_BRIDGE_HOST`  | CDP host for browser connection                    | `127.0.0.1` |
+| `CEF_BRIDGE_PORT`  | CDP port for browser connection                    | `9223`      |
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/lespaceman/agent-web-interface
+cd agent-web-interface
+npm install
+npm run build
+```
+
+Configure the MCP server in your client according to its MCP integration instructions.
+
+---
+
+## Architecture Overview
+
+Agent Web Interface separates concerns into three layers:
+
+- **Browser lifecycle** — page creation, navigation, teardown
+- **Semantic snapshot generation** — regions, elements, identifiers
+- **Action resolution** — mapping agent intent to browser actions
+
+This separation allows each layer to evolve independently while keeping agent-visible behavior stable.
+
+---
+
+## Status
+
+Agent Web Interface is under active development.
+APIs and snapshot formats may evolve as real-world agent usage informs the design.
+
+Feedback from practitioners building agent systems is especially welcome.
+
+---
+
+## License
+
+MIT

package/dist/src/browser/ensure-browser.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Lazy Browser Initialization
+ *
+ * Ensures a browser is ready before tool execution.
+ * If no browser is running, launches or connects based on CLI configuration.
+ */
+import type { SessionManager } from './session-manager.js';
+/**
+ * Options for lazy browser initialization.
+ */
+export interface EnsureBrowserOptions {
+    /** Run browser in headless mode (default: false) */
+    headless?: boolean;
+    /** Use isolated temp profile (default: false) */
+    isolated?: boolean;
+    /** HTTP endpoint URL for connecting to existing browser */
+    browserUrl?: string;
+    /** WebSocket endpoint URL for connecting to existing browser */
+    wsEndpoint?: string;
+    /** Auto-connect to Chrome 144+ via DevToolsActivePort */
+    autoConnect?: boolean;
+    /** Chrome user data directory */
+    userDataDir?: string;
+    /** Chrome channel */
+    channel?: 'chrome' | 'chrome-canary' | 'chrome-beta' | 'chrome-dev';
+    /** Path to Chrome executable */
+    executablePath?: string;
+}
+/**
+ * Ensure browser is ready for tool execution.
+ *
+ * If browser is already running, returns immediately.
+ * Otherwise, launches or connects based on provided options.
+ *
+ * @param session - SessionManager instance
+ * @param options - Configuration options from CLI
+ */
+export declare function ensureBrowserReady(session: SessionManager, options: EnsureBrowserOptions): Promise<void>;
+//# sourceMappingURL=ensure-browser.d.ts.map

package/dist/src/browser/ensure-browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-browser.d.ts","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAK3D;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,iDAAiD;IACjD,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB,2DAA2D;IAC3D,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAC;IAEpB,yDAAyD;IACzD,WAAW,CAAC,EAAE,OAAO,CAAC;IAEtB,iCAAiC;IACjC,WAAW,CAAC,EAAE,MAAM,CAAC;IAErB,qBAAqB;IACrB,OAAO,CAAC,EAAE,QAAQ,GAAG,eAAe,GAAG,aAAa,GAAG,YAAY,CAAC;IAEpE,gCAAgC;IAChC,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AASD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,IAAI,CAAC,CAwCf"}

package/dist/src/browser/ensure-browser.js

@@ -0,0 +1,65 @@
+/**
+ * Lazy Browser Initialization
+ *
+ * Ensures a browser is ready before tool execution.
+ * If no browser is running, launches or connects based on CLI configuration.
+ */
+import { getLogger } from '../shared/services/logging.service.js';
+const logger = getLogger();
+/**
+ * Determine if we should connect to an existing browser vs launch new one.
+ */
+function shouldConnect(options) {
+    return !!(options.browserUrl ?? options.wsEndpoint ?? options.autoConnect);
+}
+/**
+ * Ensure browser is ready for tool execution.
+ *
+ * If browser is already running, returns immediately.
+ * Otherwise, launches or connects based on provided options.
+ *
+ * @param session - SessionManager instance
+ * @param options - Configuration options from CLI
+ */
+export async function ensureBrowserReady(session, options) {
+    // Fast path: browser already running
+    if (session.isRunning()) {
+        return;
+    }
+    const mode = shouldConnect(options) ? 'connect' : 'launch';
+    logger.info('Lazy browser initialization triggered', { mode });
+    try {
+        if (shouldConnect(options)) {
+            // Connect to existing browser
+            await session.connect({
+                browserURL: options.browserUrl,
+                browserWSEndpoint: options.wsEndpoint,
+                autoConnect: options.autoConnect,
+                userDataDir: options.userDataDir,
+            });
+        }
+        else {
+            // Launch new browser
+            await session.launch({
+                headless: options.headless ?? false,
+                isolated: options.isolated ?? false,
+                userDataDir: options.userDataDir,
+                channel: options.channel,
+                executablePath: options.executablePath,
+            });
+        }
+        logger.info('Browser initialized successfully', { mode });
+    }
+    catch (error) {
+        logger.error('Browser initialization failed', error instanceof Error ? error : undefined, {
+            mode,
+            browserUrl: options.browserUrl,
+            wsEndpoint: options.wsEndpoint,
+            autoConnect: options.autoConnect,
+            headless: options.headless,
+            userDataDir: options.userDataDir,
+        });
+        throw error;
+    }
+}
+//# sourceMappingURL=ensure-browser.js.map

package/dist/src/browser/ensure-browser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ensure-browser.js","sourceRoot":"","sources":["../../../src/browser/ensure-browser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,SAAS,EAAE,MAAM,uCAAuC,CAAC;AAElE,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;AA+B3B;;GAEG;AACH,SAAS,aAAa,CAAC,OAA6B;IAClD,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,UAAU,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,OAAuB,EACvB,OAA6B;IAE7B,qCAAqC;IACrC,IAAI,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;QACxB,OAAO;IACT,CAAC;IAED,MAAM,IAAI,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC;IAC3D,MAAM,CAAC,IAAI,CAAC,uCAAuC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAE/D,IAAI,CAAC;QACH,IAAI,aAAa,CAAC,OAAO,CAAC,EAAE,CAAC;YAC3B,8BAA8B;YAC9B,MAAM,OAAO,CAAC,OAAO,CAAC;gBACpB,UAAU,EAAE,OAAO,CAAC,UAAU;gBAC9B,iBAAiB,EAAE,OAAO,CAAC,UAAU;gBACrC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,WAAW,EAAE,OAAO,CAAC,WAAW;aACjC,CAAC,CAAC;QACL,CAAC;aAAM,CAAC;YACN,qBAAqB;YACrB,MAAM,OAAO,CAAC,MAAM,CAAC;gBACnB,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;gBACnC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,KAAK;gBACnC,WAAW,EAAE,OAAO,CAAC,WAAW;gBAChC,OAAO,EAAE,OAAO,CAAC,OAAO;gBACxB,cAAc,EAAE,OAAO,CAAC,cAAc;aACvC,CAAC,CAAC;QACL,CAAC;QACD,MAAM,CAAC,IAAI,CAAC,kCAAkC,EAAE,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,CAAC,KAAK,CAAC,+BAA+B,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,EAAE;YACxF,IAAI;YACJ,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,UAAU,EAAE,OAAO,CAAC,UAAU;YAC9B,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CAAC;QACH,MAAM,KAAK,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/src/browser/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser Module
+ *
+ * Exports for browser lifecycle management.
+ */
+export { PageRegistry, type PageHandle } from './page-registry.js';
+export { SessionManager, type LaunchOptions, type ConnectOptions, type ConnectionState, type ConnectionStateChangeEvent, } from './session-manager.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/browser/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,UAAU,EAAE,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,EACd,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,0BAA0B,GAChC,MAAM,sBAAsB,CAAC"}

package/dist/src/browser/index.js

@@ -0,0 +1,8 @@
+/**
+ * Browser Module
+ *
+ * Exports for browser lifecycle management.
+ */
+export { PageRegistry } from './page-registry.js';
+export { SessionManager, } from './session-manager.js';
+//# sourceMappingURL=index.js.map

package/dist/src/browser/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/browser/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,YAAY,EAAmB,MAAM,oBAAoB,CAAC;AACnE,OAAO,EACL,cAAc,GAKf,MAAM,sBAAsB,CAAC"}

package/dist/src/browser/page-network-tracker.d.ts

@@ -0,0 +1,96 @@
+/**
+ * Page Network Tracker
+ *
+ * Tracks in-flight network requests for a page and provides a reliable
+ * "network quiet" wait mechanism. Unlike Puppeteer's waitForNetworkIdle(),
+ * this tracks requests triggered after page load (e.g., by user actions).
+ *
+ * Uses a generation counter to safely handle navigation - late events from
+ * previous documents are ignored.
+ */
+import type { Page } from 'puppeteer-core';
+/**
+ * Tracks network requests for a single page.
+ *
+ * Attach to a page via `attach()`, then use `waitForQuiet()` to wait for
+ * network activity to settle. Call `markNavigation()` when navigating to
+ * safely reset state without race conditions.
+ */
+export declare class PageNetworkTracker {
+    private page;
+    private inflightCount;
+    private generation;
+    private currentGeneration;
+    private quietTimer;
+    private quietWindowMs;
+    private quietResolvers;
+    private onRequest;
+    private onRequestFinished;
+    private onRequestFailed;
+    /**
+     * Attach network event listeners to a page.
+     *
+     * Must be called before `waitForQuiet()` can be used.
+     * Safe to call multiple times - will detach previous listeners first.
+     */
+    attach(page: Page): void;
+    /**
+     * Detach all event listeners and cleanup timers.
+     *
+     * Call this when the page is closed or no longer needs tracking.
+     */
+    detach(): void;
+    /**
+     * Mark that a navigation occurred.
+     *
+     * This safely resets state by bumping the generation counter, so any
+     * late events from the previous document are ignored. Use this instead
+     * of directly resetting state to avoid race conditions.
+     */
+    markNavigation(): void;
+    /**
+     * Wait for network to become quiet (no inflight requests for quietWindowMs).
+     *
+     * @param timeoutMs - Maximum time to wait before returning false
+     * @param quietWindowMs - Time with 0 inflight requests to consider "idle"
+     * @returns true if network became quiet, false if timed out (never throws)
+     */
+    waitForQuiet(timeoutMs: number, quietWindowMs?: number): Promise<boolean>;
+    /**
+     * Get current inflight request count (for debugging/testing).
+     */
+    getInflightCount(): number;
+    /**
+     * Check if tracker is attached to a page.
+     */
+    isAttached(): boolean;
+    private cancelQuietTimer;
+    private checkQuiet;
+    private startQuietTimer;
+    /**
+     * Create and attach event handlers for the current generation.
+     */
+    private createAndAttachHandlers;
+    /**
+     * Remove event handlers from a page.
+     */
+    private removeHandlers;
+}
+/**
+ * Get or create a network tracker for a page.
+ *
+ * Note: This does NOT automatically attach the tracker.
+ * Call `tracker.attach(page)` after getting the tracker.
+ */
+export declare function getOrCreateTracker(page: Page): PageNetworkTracker;
+/**
+ * Remove and detach the tracker for a page.
+ *
+ * Call this when a page is closed to ensure proper cleanup.
+ */
+export declare function removeTracker(page: Page): void;
+/**
+ * Check if a page has a tracker attached.
+ */
+export declare function hasTracker(page: Page): boolean;
+//# sourceMappingURL=page-network-tracker.d.ts.map

package/dist/src/browser/page-network-tracker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page-network-tracker.d.ts","sourceRoot":"","sources":["../../../src/browser/page-network-tracker.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAe,MAAM,gBAAgB,CAAC;AAKxD;;;;;;GAMG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,iBAAiB,CAAK;IAG9B,OAAO,CAAC,UAAU,CAA+B;IACjD,OAAO,CAAC,aAAa,CAAmC;IACxD,OAAO,CAAC,cAAc,CAAyE;IAG/F,OAAO,CAAC,SAAS,CAA6C;IAC9D,OAAO,CAAC,iBAAiB,CAA6C;IACtE,OAAO,CAAC,eAAe,CAA6C;IAEpE;;;;;OAKG;IACH,MAAM,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI;IAaxB;;;;OAIG;IACH,MAAM,IAAI,IAAI;IAmBd;;;;;;OAMG;IACH,cAAc,IAAI,IAAI;IAYtB;;;;;;OAMG;IACG,YAAY,CAChB,SAAS,EAAE,MAAM,EACjB,aAAa,GAAE,MAAgC,GAC9C,OAAO,CAAC,OAAO,CAAC;IAuBnB;;OAEG;IACH,gBAAgB,IAAI,MAAM;IAI1B;;OAEG;IACH,UAAU,IAAI,OAAO;IAMrB,OAAO,CAAC,gBAAgB;IAOxB,OAAO,CAAC,UAAU;IAMlB,OAAO,CAAC,eAAe;IAavB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IA6B/B;;OAEG;IACH,OAAO,CAAC,cAAc;CAWvB;AAYD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,kBAAkB,CAOjE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAM9C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,OAAO,CAE9C"}