# ⚡ MEXX-Browser-Agent (v3.0)

> **The High-Performance Autonomous Browser Agent & Execution Runtime.**
> Give AI agents access to your authentic, daily-driver Chrome — without stealing cursor focus, leaking tokens, or bypassing security controls.

Unlike traditional headless browser automations (which spin up isolated, cold, unauthenticated instances that break 2FA and consume gigabytes of RAM), **MEXX-Browser-Agent** operates as a high-performance **Local Browser Runtime**:
It connects AI agents (via Model Context Protocol, WebSocket, or REST) directly to your **existing Google Chrome browser**. Agents can inspect reactive DOM events, extract WebGL/WebGPU canvases directly from VRAM, record and replay deterministic workflows, and automate multiple background tabs in parallel — while you continue typing, coding, and browsing in the same window without cursor theft or window disruption.

---

## 🌟 Why MEXX v3.0?

| Feature | Headless MCP / Chrome DevTools | Traditional Vision Agents (`browser-use`) | **MEXX v3.0** |
| :--- | :--- | :--- | :--- |
| **Workflow Paradigm** | Bot-only (clean blank window) | Autonomous screenshot/coordinate loop | **Human Copilot & Autonomous Runtime** |
| **Authentication** | ❌ Breaks on 2FA, SSO, passkeys | ❌ Requires re-login or cookie exports | ✅ **100% Native:** Uses your active Chrome cookies & SSO |
| **Window & Mouse Focus** | ❌ Hijacks OS window / steals mouse | ❌ Flaky coordinate clicks, window flickering | ✅ **Zero-Focus Shadow Execution:** Coexists with you typing |
| **Waiting for Page State** | Polling loop (burns tokens & CPU) | Continuous screenshot loop ($$$) | ⚡ **Event-Driven Sleep/Wake:** no LLM tokens while waiting, near-zero idle CPU |
| **World State Context** | ❌ Dumps 50,000 token raw DOM | ❌ Multi-megabyte image tokens | ⚡ **Semantic Context Compression:** ~50 tokens per tab* |
| **Workflows & Macros** | ❌ Re-queries LLM for every action | ❌ Every step burns 1,000–5,000 tokens | 🚀 **Deterministic Replay Runner:** no LLM calls, ~100ms/step* |
| **Self-Healing Resiliency** | ❌ Breaks on minor CSS class changes | ❌ Re-evaluates entire screenshot with LLM | 🛡️ **Target Fingerprint Cascade:** ARIA, TestID, Levenshtein |
| **Security & Guardrails** | ❌ None (blind execution) | ⚠️ Post-hoc prompt guardrails | 🔒 **Deterministic R0–R4 Risk Firewall + Human Gate** |
| **Canvas & WebGPU** | ❌ Blind (Cannot inspect GPU buffers) | ❌ Only sees outer canvas image | ✅ **In-Memory WebGL/WebGPU VRAM Telemetry** |
| **RAM Footprint** | 2,000–4,000 MB (heavy process pool) | 1,500–3,000 MB | 🪶 **<100 MB RAM overhead**\* |

\* Design targets measured with the local harness — reproduce via `npm run benchmark` (see `benchmark/`). Actual figures depend on machine, page, and workload; verify on your setup before quoting.

---

## 🏛️ Core Architecture Pillars

MEXX v3.0 is built on a clean separation of concerns:  
**AI decides Intent → Policy controls Permissions → Deterministic Engine executes.**

```mermaid
flowchart TD
    subgraph AgentLayer ["AI Agent Layer (Gehirn)"]
        Agent["Antigravity / Claude Desktop / Cursor / MCP Client"]
    end

    subgraph MEXXRuntime ["MEXX v3.0 Runtime (:8910 / :8911)"]
        direction TB
        ZeroTrust["Zero-Trust Security Gate (256-bit Token + Origin Check)"]
        Policy["Security Firewall (R0–R4 Classification & Invariant Enforcement)"]
        WorldState["Shared Semantic World State (Revisions, Leases, 50-Token Diff)"]
        EventEngine["Event-Driven Sleep/Wake (DOM Mutation Matcher)"]
        WorkflowEngine["Deterministic Workflow Runner & Self-Healing Engine"]
        
        ZeroTrust --> Policy
        Policy --> WorldState
        Policy --> EventEngine
        Policy --> WorkflowEngine
    end

    subgraph ChromeLayer ["Daily-Driver Google Chrome"]
        direction TB
        ExtWorker["Extension Service Worker (MV3)"]
        BackgroundTabs["Silent Background Tabs (CDP Shadow Execution)"]
        ForegroundTab["User Active Tab (Zero-Focus Coexistence)"]
        
        ExtWorker <--> BackgroundTabs
        ExtWorker <--> ForegroundTab
    end

    Agent <==>|MCP / WebSocket / REST| ZeroTrust
    WorkflowEngine <==>|Fast CDP / DOM Pipeline| ExtWorker
```

---

## 🚀 Key Innovations in v3.0

### 1. Event-Driven Sleep/Wake Engine (`browser_wait_for_event`)
* **Zero Token Cost While Waiting:** Agents no longer poll in busy loops. Calling `browser_wait_for_event` suspends the agent asynchronously until the target condition occurs.
* **In-Browser Matching:** Monitored directly inside Chrome's `content.js` with microtask batching (`queueMicrotask`) and 150ms anti-flapping stabilization.
* **Supported Events:** `DOM_APPEAR`, `DOM_CHANGE`, `TEXT_MATCH`, `NAVIGATE`, `DOWNLOAD_COMPLETE`.

### 2. Shared Semantic World State (`browser_get_world_state`)
* **Context Compression (~50 vs. ~50,000 tokens):** Extracts concise semantic snapshots per tab: modal status, authentication state, dirty forms, active alerts, and primary CTAs.
* **Differential Queries (`GET /world-state/:tabId/diff`):** Only streams high-level semantic deltas (`MODAL_OPENED`, `FORM_DIRTY`).
* **Concurrency Leases (`browser_acquire_lease`):** Multi-step critical operations obtain exclusive tab leases (`ttlMs: 5000–60000`) to prevent agent collisions.
* **Human Precedence Guarantee:** Any user interaction immediately revokes automated leases.

### 3. Behavior Memory & Deterministic Workflow Engine
* **"Record first, parameterize second":** Capture user browser flows once, parameterize variables dynamically (`${email}`, `${searchQuery}`), and replay deterministically.
* **Token-Free Replay (Zero LLM Calls):** Runs in **~100–200 ms per step\*** without querying an LLM during execution.
* **Multi-Signal Target Fingerprints:** Elements are identified by a resilient cascade (TestID > ARIA > Name > Stable ID > Text Anchor > Semantic CSS with Tailwind entropy filtering).
* **Levenshtein Tolerance (>0.75):** Absorbs minor UI copy variations ("Rechnung herunterladen" vs. "Rechnung laden") without triggering healing failures.
* **Anti-Poisoning Staged Repairs:** Healed selectors are placed into `stagedRepairs` and only committed to immutable versions (`version++`) upon verification.

### 4. Hardened Security & Defense-in-Depth
* **Deterministic Risk Classes (R0–R4):**
  * `R0`: Read-only inspection (`readTab`, `extractCanvas`, `getLiveContext`).
  * `R1`: Passive navigation & non-destructive control (`scroll`, `closeTab`).
  * `R2`: State alterations & form submits (Policy-guided).
  * `R3`: Destructive mutations (`delete`, `drop`, `cancel subscription`). Mandatory Human Approval.
  * `R4`: High-risk domains (banking, crypto, payment gateways like Stripe/PayPal). Mandatory Human Approval.
* **Ambiguity Hard-Stop:** If self-healing detects multiple candidate matches (`candidateCount > 1`), autonomous guessing is strictly prohibited. Execution halts with HTTP 428 (`ambiguous: true`).
* **Target Identity Binding (TOCTOU Protection):** Re-validates target presence and visibility synchronously immediately prior to clicking or filling.
* **Zero PII / Secret-Leak on Normal Inputs:** Automatically detects API keys (`sk_...`, `ghp_...`), JWTs, Slack tokens, credit cards, and IBANs across all inputs and sanitizes disk storage.
* **Anti-Collision Modal Protection:** Modals containing financial or destructive signals (`DESTRUCTIVE_KEYWORDS`, `FINANCIAL_KEYWORDS`) override automatic interstitial dismissal and enforce human review.

---

## 🥊 Ecosystem Comparison: Where MEXX Stands

| Dimension | `browser-use` | `citrolabs/ego-lite` | `jo-inc/camofox-browser` | **MEXX v3.0** |
| :--- | :--- | :--- | :--- | :--- |
| **Core Architecture** | Python + Playwright CDP wrapper | Standalone Custom-Chromium Fork | C++ Patched Camoufox (Firefox fork) | **Chrome MV3 Extension + Zero-Trust Local Bridge** |
| **Browser Runtime** | Ephemeral, clean Chromium instance | Separate dedicated application with Spaces | Headless Docker / VPS REST server | **Your authentic, daily-driver Google Chrome** |
| **Authentication / 2FA** | ❌ Fails on 2FA, passkeys & logins | ⚠️ Requires re-login inside Ego Browser | ❌ Requires Netscape cookie file import | ✅ **100% Native:** All existing cookies, 2FA, SSO active |
| **Focus & Mouse Behavior** | ❌ Takes OS window focus (`bringToFront`) | ✅ Multi-space isolation inside Ego app | ✅ Headless (no OS window) | ✅ **Zero-Focus Shadow Execution** (type while it runs) |
| **Token Efficiency** | ❌ Massive (LLM screenshot loop) | ⚠️ High (continuous DOM serialization) | ⚠️ High (continuous text dumps) | 🚀 **Lean:** ~50-token world state\* + LLM-free workflows |
| **Execution Speed** | 3,000 – 15,000 ms per step† | 1,000 – 3,000 ms per step† | 800 – 2,000 ms per step† | ⚡ **~100 – 200 ms per step\*** |
| **Password Managers & Plugins** | ❌ None (isolated process) | ❌ None (custom fork lacks your plugins) | ❌ None (headless container) | ✅ **Full Compatibility:** 1Password, Bitwarden, uBlock intact |
| **Canvas, WebGL & WebGPU** | ❌ Blind (Cannot inspect GPU memory) | ❌ Text/accessibility focus only | ❌ Headless accessibility focus | ✅ **Deep In-Memory:** Direct VRAM buffer, rAF sync, WebGPU limits |
| **Enterprise IT Compliance** | ⚠️ Unsigned headless executables | ❌ Third-party Chromium binaries often blocked | ⚠️ Remote scraping proxy | ✅ **No third-party binaries:** runs as an extension on managed Chrome |

\* Own figures: design targets, reproducible via `npm run benchmark` (see `benchmark/`).
† Competitor figures are rough public estimates, not independently benchmarked by us. If you maintain one of these projects and a cell is wrong, please open an issue — corrections are welcome.

---

## 🛠️ MCP Tools Suite

Core tools at a glance (23 total) — full reference with risk notes in [TOOLS.md](TOOLS.md):

| Tool Name | What it does |
| :--- | :--- |
| `browser_read_tab` | **Silent Shadow-Read** of any background tab without stealing focus. |
| `browser_get_world_state` | Compressed semantic state (~50 tokens) or differential deltas. |
| `browser_wait_for_event` | Event-driven sleep/wake with zero token cost while waiting. |
| `browser_run_workflow` | Deterministic, token-free replay of recorded macros. |
| `browser_click` / `browser_fill` | Self-healing semantic interaction, incl. rich-text editors. |
| `browser_extract_canvas` | WebGL/WebGPU framebuffer and hardware telemetry. |

---

## ⚖️ Known Limitations & Transparent Boundaries

To maintain high technical integrity, MEXX clearly communicates its operational boundaries:

1. **Keyword Heuristics are Baseline Sensors, Not Complete Semantics:**  
   `DESTRUCTIVE_KEYWORDS` and `FINANCIAL_KEYWORDS` effectively catch common confirmation dialogues ("löschen", "delete", "buy", "order"). However, atypical wording (e.g., "Finalisieren", "Vorgang abschließen" on custom checkout steps) or icon-only buttons without text may not trigger keyword alerts. MEXX combines keywords with action semantics and structural modal detection, but does not claim 100% natural language comprehension without human oversight on unknown critical paths.
2. **Test Suite Scope (93/93 Tests, 6 Suites):**  
   The 100% green test suite proves strict contract compliance, deterministic execution, and state machine integrity against comprehensive internal fixture suites and mocked scenarios. Real-world third-party websites exhibit immense DOM variance; wild adversarial edge cases are addressed through strict **Fail-Closed** mechanics.
3. **Tab Lifecycle & Focus Invariant:**  
   The `closeTab` action is designed to clean up automated background tabs and prevent memory leaks. Automated workflows must verify tab ownership to prevent closing tabs where the user is actively working.
4. **Anti-Detection & Bot Shields:**  
   MEXX is an assistive copilot inside your authentic desktop Chrome. It does not spoof hardware fingerprints or bypass anti-bot shields (Cloudflare Turnstile, Akamai).

---

## 🚀 1-Click Launch

Prerequisites: **Node.js 20+** and a **recent Google Chrome** (MV3-capable, Chrome 88+) on **Windows, macOS, or Linux**.

Get up and running in **one command**:

```bash
# If cloned locally:
npm start

# Or with tool-named alias:
npm run copilot

# Or on a fresh machine — everything included (clone, install, build, launch):
git clone https://github.com/Jera1807/mexx-browser-agent.git && cd mexx-browser-agent && npm install && npm start

# (After the first npm publish, this becomes: npx mexx-browser-agent)
```

**What this command handles automatically:**
1. **Generates Zero-Trust Token:** Creates a cryptographically secure 256-bit session token (`.bridge-token`) synced directly into the extension bundle (`token.json`).
2. **Auto-detects Chrome:** Finds your local `chrome.exe` on Windows, macOS, or Linux.
3. **Auto-loads Extension:** Launches Chrome with `--load-extension` pre-configured.
4. **Auto-configures MCP:** Detects your `claude_desktop_config.json` and registers `mexx-browser-agent` as an active MCP tool.
5. **Starts Live Bridge:** Starts the high-speed WebSocket (`:8910`) and HTTP API (`:8911`) with strict origin verification.

---

## 🔒 Security Policy & Privacy

[SECURITY.md](SECURITY.md) documents the threat model, the deterministic R0–R4 risk classes, the human-approval flow (single-use tokens, TOCTOU binding), and the fail-closed invariants.

**Privacy & telemetry:** the extension sends nothing to external servers. All traffic stays on localhost (`127.0.0.1:8910`/`:8911`). The only data written to disk is local: the session token (`.bridge-token`), the append-only audit log (`audit.jsonl`), and recorded workflows (`workflows.json`) — all git-ignored by default. There is no analytics, no tracking, no cloud component.

---

## 🤝 Contributing

Issues and pull requests are welcome once the repository is public. Please run `npm run release-check` (build, audit, secret scan, full test suite) before submitting. Security vulnerabilities: see [SECURITY.md](SECURITY.md) for responsible disclosure.

---

## 📄 License
Apache-2.0 © Jerome Lichy — see [LICENSE](LICENSE). The patent grant and retaliation clause protect contributors and users alike.