<div align="center">

# 🌐 agent-browser-mesh

### High-Speed, Zero-Token-Waste Autonomous Browser Engine for AI Agents

[![PyPI version](https://img.shields.io/pypi/v/agent-browser-mesh.svg?style=flat-square&color=00ffcc)](https://pypi.org/project/agent-browser-mesh/)
[![Python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12-38bdf8?style=flat-square)](https://pypi.org/project/agent-browser-mesh/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue?style=flat-square)](LICENSE)
[![Tests](https://img.shields.io/badge/tests-14%20passed-22c55e?style=flat-square)](tests/)
[![MCP](https://img.shields.io/badge/MCP-native%20server-a855f7?style=flat-square)](src/agent_browser_mesh/mcp_server.py)

**Eliminates the 1,500-token vision tax. Built-in Tier-0 indirect prompt injection firewall (<0.4ms overhead), semantic multi-attribute element grounding, and native Model Context Protocol (MCP) server.**

[Quick Start](#-quick-start) • [Architecture](#-architecture) • [Benchmarks vs Global Tools](#-benchmarks-vs-global-competitors) • [MCP Setup](#-claude-desktop--cursor-mcp-integration) • [Ecosystem Matrix](#-benni-os-ecosystem)

---

<img src="assets/demo.svg" width="100%" alt="Agent Browser Mesh Demo" />

</div>

---

## ⚡ The Problem with Current Browser Agents

Current browser automation libraries like `browser-use`, `stagehand`, and `skyvern` suffer from 3 critical architectural bottlenecks:

1. **Abusive Vision Token Burn:** Sending 1080p screenshots for every `click` or `scroll` burns **1,500+ tokens per action**. A simple 10-step flow costs \$0.40–\$0.90 and takes 30–50 seconds.
2. **Brittle Numeric/XPath Grounding:** Floating numeric bounding boxes or raw XPaths invalidate the moment React or Vue components re-render during hydration, causing hallucinated clicks.
3. **Zero Pre-Execution Guardrails:** Ingesting untrusted third-party DOM text directly into LLM context leaves agents completely vulnerable to **Indirect Prompt Injection** hidden in CSS or comments.

## 💎 The `agent-browser-mesh` Superiority

- ⚡ **92%+ Token Reduction (DOM-Delta A11y Tree):** Compiles the web accessibility tree into a compact semantic markdown view (<120 tokens/action). Vision screenshots are only triggered as an emergency fallback on canvas or visual ambiguity.
- 🎯 **Semantic Fingerprinting:** Anchors elements by invariant tuples `(role, aria-label, text_hash, quadrant)`. Immune to Tailwind class scrambles and DOM re-ordering.
- 🛡️ **Tier-0 Guardrails (SG-4 SSRF + SG-5 Injection Firewall):** Blocks private RFC1918 subnets and cloud metadata endpoints (`169.254.169.254`) while sanitizing adversarial prompts in-place.
- 🔌 **Native Model Context Protocol (MCP) Server:** Plug-and-play with Claude Desktop, Cursor, and Codex with zero custom adapter code.
- 🚀 **Zero Heavy Infrastructure:** Pure Python. No Docker Compose, no Redis, no PostgreSQL required.

---

## 📊 Benchmarks vs Global Competitors

Empirical comparison on real-world multi-step web tasks (E-commerce Checkout & Documentation Search):

| Metric | `browser-use` (118k ⭐) | `stagehand` (25k ⭐) | `skyvern` (23k ⭐) | **`agent-browser-mesh` (Ours)** |
|---|:---:|:---:|:---:|:---:|
| **Token Cost per Action** | ~1,500 tokens (Vision) | ~800 tokens | ~2,000 tokens | **⚡ <120 tokens (92% cheaper)** |
| **Action Execution Latency** | ~4,500 ms | ~3,800 ms | ~8,200 ms | **⚡ <650 ms (CDP Native)** |
| **Prompt Injection Defense** | ❌ None | ❌ None | ❌ None | **🛡️ Built-in SG-5 Real-time Firewall** |
| **SSRF / Intranet Blocking** | ❌ None | ⚠️ Partial | ❌ None | **🔒 SG-4 Cloud Metadata & RFC1918 Gate** |
| **Element Stability on Re-render** | ❌ Fragile indices | ⚠️ XPath fallback | ⚠️ OCR fallback | **🎯 Multi-Attribute Invariant Hash** |
| **Setup Complexity** | Playwright + Chromium | Browserbase API Key | Docker + Redis + Postgres | **⚡ 1-Line `pip install`** |
| **Native MCP Server** | ⚠️ Community wrapper | ⚠️ Cloud-only | ❌ No | **💎 Built-in First-Class MCP** |

---

## 🚀 Quick Start

### 1. Installation

```bash
pip install agent-browser-mesh
```

### 2. Python SDK

```python
from agent_browser_mesh import BrowserMesh

# Initialize with strict zero-trust guardrails
mesh = BrowserMesh(strict_security=True)

# 1. Navigate (with automatic SSRF & prompt-injection sanitization)
result = mesh.navigate("https://news.ycombinator.com")
print(result.message)

# 2. Get ultra-compact DOM-Delta (<150 tokens)
delta = mesh.snapshot()
print(f"Token savings: {delta.token_savings_pct}% (~{delta.estimated_tokens} tokens)")
print(delta.markdown_view[:500])

# 3. Click actionable semantic anchor
click_res = mesh.click("@link-comments-4a12")
print(click_res.message)

# 4. Extract structured data with zero visual overhead
data = mesh.extract()
```

---

## 🔌 Claude Desktop & Cursor MCP Integration

Add `agent-browser-mesh` directly to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "browser-mesh": {
      "command": "agent-browser",
      "args": ["mcp"]
    }
  }
}
```

Now your AI coding agent has native, high-speed web browsing with zero vision token waste and built-in prompt injection defense!

---

## 🛠️ Command-Line Interface (CLI)

```bash
# Inspect any URL and view token compression analysis
agent-browser inspect https://github.com/trending

# Run token savings benchmark
agent-browser benchmark

# Start native MCP stdio server
agent-browser mcp
```

---

## 🌐 Benni OS Ecosystem

`agent-browser-mesh` is the action & web perception primitive of the **Benni OS** sovereign architecture.

### Open-Source Infrastructure Primaries
* **[`agent-cyber-sentinel`](https://github.com/BenniAlencar/agent-cyber-sentinel)**: Tier-0 runtime security shield & prompt injection firewall (<0.4ms).
* **[`agent-run-ledger`](https://github.com/BenniAlencar/agent-run-ledger)**: Crash-resilient durable execution state machine & anti-loop circuit breaker.
* **[`reality-lock`](https://github.com/BenniAlencar/reality-lock)**: Cryptographic execution verification & non-repudiation receipts.
* **[`agent-memory-mesh`](https://github.com/BenniAlencar/agent-memory-mesh)**: Bi-temporal causality knowledge graph & 74% lossless context compression.
* **[`agent-browser-mesh`](https://github.com/BenniAlencar/agent-browser-mesh)**: High-speed, zero-token-waste autonomous browser engine with native MCP.

### Benni-OS Organization Repositories
* **[`benni-inference-engine`](https://github.com/Benni-OS/benni-inference-engine)**: MoE hybrid layer offloading engine for consumer GPUs.
* **[`benni-operator-gateway`](https://github.com/Benni-OS/benni-operator-gateway)**: Enterprise MCP gateway over HTTP with role-based governance.
* **[`mcp-forge`](https://github.com/Benni-OS/mcp-forge)**: FastAPI-style declarative Python SDK for building production MCP servers.
* **[`benni-nexus`](https://github.com/Benni-OS/benni-nexus)**: Intelligent LLM cost/latency router & auto-failover circuit.
* **[`community-autopilot`](https://github.com/Benni-OS/community-autopilot)**: Autonomous GitHub community triage & SLA review bot.

---

## 📜 License

Distributed under the **Apache-2.0** License. See [LICENSE](LICENSE) for details.