@weavetab/mcp 2.5.0-beta.2 → 2.5.0-beta.5

package/docs/get-started/introduction.md

@@ -1,60 +1,60 @@
----
-title: "Introduction"
-description: "What Weavetab is, Layer 0 CDP architecture, and design tenets."
-product: mcp
-section: get-started
-icon: BookOpen
-slug: introduction
----
-
-# Introduction
-
-Weavetab is a production-grade, local **Model Context Protocol (MCP) server** that grants AI agents human-like control over Chromium browsers and native **Electron desktop applications** (VS Code, Discord, Slack, Figma, Obsidian, Postman, Antigravity IDE, etc.) — communicating directly over the **Chrome DevTools Protocol (CDP)** at Layer 0.
-
-No WebDriver. No browser binary downloads. No Playwright or Puppeteer abstraction layer. No cloud dependency. Tool invocations resolve in **3–8 ms** of mean latency.
-
-## Synchronized Ecosystem Releases
-
-Both **`@weavetab/mcp`** and the **`@weavetab/sdk`** share synchronized release lines. Every capability introduced in the core runtime is immediately available in the developer SDK with 100% type safety and zero version mismatch.
-
-```bash
-# Install core Weavetab MCP server globally
-npm install -g @weavetab/mcp@latest
-
-# Or run directly via npx
-npx -y @weavetab/mcp@latest
-
-# Install Weavetab Developer SDK as a dev dependency
-npm install -D @weavetab/sdk@latest
-```
-
-## Design Tenets
-
-| Tenet | Implementation |
-|---|---|
-| **Ultra-Low Latency** | Sub-10 ms tool execution via direct CDP WebSocket connections |
-| **Universal Control** | Native orchestration across Chromium web tabs and any Electron desktop app |
-| **Autonomous CAPTCHA** | Zero-API solving (Cloudflare Turnstile, GeeTest, reCAPTCHA) via human Bézier mouse physics |
-| **Security & RBAC** | 4-tier RBAC + domain policies + Blind Credential Injection + profile isolation |
-| **Token Efficiency** | Semantic Delta diffing (up to 97% reduction) + intelligent DOM pruning |
-| **Stealth & Physics** | Ghost Cursor (Bézier curves), human typing jitter, and CDP early-script fingerprint spoofing |
-| **Self-Learning** | Per-domain session memory, framework detection, and automated loop recovery |
-| **Zero Cloud** | Pure local computation. No external telemetry or cloud tracking unless explicitly opted in |
-
-## What You Get
-
-- **46 built-in MCP tools** covering DOM vision, input synthesis, desktop apps, tabs, network interception, office files, design extraction, and plugin lifecycle
-- **Universal Desktop App Runtime** — seamlessly control Chrome and native Electron apps (Discord, Figma, VS Code) side-by-side without port conflicts
-- **Autonomous Zero-API CAPTCHA Solver** — solve Cloudflare Turnstile, GeeTest, and reCAPTCHA locally via CDP mouse physics with $0 API costs
-- **Two transport modes** — stdio (Claude Desktop, Cursor, VS Code, Windsurf, Antigravity) and WebSocket (`--ws --port 3000`)
-- **Four RBAC roles** — `admin`, `operator`, `viewer`, and `automation`
-- **Per-domain policies** — ring-fences sensitive banking, internal, and production surfaces
-- **Blind Injection** — credentials resolved server-side from `secrets.json` and never exposed to the LLM
-- **Extensible Plugin System** — auto-discovers and mounts custom MCP tools from `node_modules`
-
-## Next Steps
-
-- **[Quickstart](/docs/quickstart)** — install and run a first mission in 60 seconds
-- **[Desktop & Electron Apps](/docs/electron-apps)** — configure and control desktop apps
-- **[Autonomous CAPTCHA Solver](/docs/captcha-solver)** — zero-API anti-bot solving
-- **[MCP Tools Reference](/docs/tools)** — full reference for all 46 built-in automation tools
+---
+title: "Introduction"
+description: "What Weavetab is, Layer 0 CDP architecture, and design tenets."
+product: mcp
+section: get-started
+icon: BookOpen
+slug: introduction
+---
+
+# Introduction
+
+Weavetab is a production-grade, local **Model Context Protocol (MCP) server** that grants AI agents human-like control over Chromium browsers and native **Electron desktop applications** (VS Code, Discord, Slack, Figma, Obsidian, Postman, Antigravity IDE, etc.) — communicating directly over the **Chrome DevTools Protocol (CDP)** at Layer 0.
+
+No WebDriver. No browser binary downloads. No Playwright or Puppeteer abstraction layer. No cloud dependency. Tool invocations resolve in **3–8 ms** of mean latency.
+
+## Synchronized Ecosystem Releases
+
+Both **`@weavetab/mcp`** and the **`@weavetab/sdk`** share synchronized release lines. Every capability introduced in the core runtime is immediately available in the developer SDK with 100% type safety and zero version mismatch.
+
+```bash
+# Install core Weavetab MCP server globally
+npm install -g @weavetab/mcp@latest
+
+# Or run directly via npx
+npx -y @weavetab/mcp@latest
+
+# Install Weavetab Developer SDK as a dev dependency
+npm install -D @weavetab/sdk@latest
+```
+
+## Design Tenets
+
+| Tenet | Implementation |
+|---|---|
+| **Ultra-Low Latency** | Sub-10 ms tool execution via direct CDP WebSocket connections |
+| **Universal Control** | Native orchestration across Chromium web tabs and any Electron desktop app |
+| **Autonomous CAPTCHA** | Zero-API solving (Cloudflare Turnstile, GeeTest, reCAPTCHA) via human Bézier mouse physics |
+| **Security & RBAC** | 4-tier RBAC + domain policies + Blind Credential Injection + profile isolation |
+| **Token Efficiency** | Semantic Delta diffing (up to 97% reduction) + intelligent DOM pruning |
+| **Stealth & Physics** | Ghost Cursor (Bézier curves), human typing jitter, and CDP early-script fingerprint spoofing |
+| **Self-Learning** | Per-domain session memory, framework detection, and automated loop recovery |
+| **Zero Cloud** | Pure local computation. No external telemetry or cloud tracking unless explicitly opted in |
+
+## What You Get
+
+- **44 built-in MCP tools** covering DOM vision, input synthesis, desktop apps, tabs, network interception, office files, design extraction, and plugin lifecycle
+- **Universal Desktop App Runtime** — control Chrome and native Electron apps (Discord, Figma, VS Code) side-by-side without port conflicts
+- **Autonomous Zero-API CAPTCHA Solver** — solve Cloudflare Turnstile, GeeTest, and reCAPTCHA locally via CDP mouse physics with $0 API costs
+- **Two transport modes** — stdio (Claude Desktop, Cursor, VS Code, Windsurf, Antigravity) and WebSocket (`weavetab --ws --port 3000`)
+- **Five RBAC roles** — `admin`, `operator`, `viewer`, `automation`, and `system`
+- **Per-domain policies** — ring-fences sensitive banking, internal, and production surfaces
+- **Blind Injection** — credentials resolved server-side from `secrets.json` and never exposed to the LLM
+- **Extensible Plugin System** — auto-discovers and mounts custom MCP tools from `node_modules`
+
+## Next Steps
+
+- **[Quickstart](quickstart.md)** — install and run a first mission in 60 seconds
+- **[Desktop & Electron Apps](../desktop-automation/electron-apps.md)** — configure and control desktop apps
+- **[Autonomous CAPTCHA Solver](../captcha-stealth/captcha-solver.md)** — zero-API anti-bot solving
+- **[MCP Tools Reference](../tools/tools.md)** — full reference for all 44 built-in automation tools

package/docs/get-started/setup-wizard.md

@@ -15,12 +15,13 @@ Run the interactive CLI configuration wizard:
 weavetab config
 ```
 
-The wizard walks through every option across 5 interactive phases. Re-run it at any time to update your saved config.
+The wizard walks through every option across 6 interactive phases. Re-run it at any time to update your saved config.
 
 ## Wizard Phases
 
-1. **Phase 1 — Essentials:** Browser path, RBAC role (`admin`, `operator`, `viewer`, `automation`), headless mode, dev mode, max tabs, actionability timeout, domain block/allow lists.
-2. **Phase 2 — Advanced:** Browser engine selection, navigation timeouts, dark mode preferences, telemetry opt-in, outbound HTTP/SOCKS proxy, domain policy modes.
-3. **Phase 3 — Save Location:** Global (`~/.weavetab/config.json`) or Project-scoped (`./.weavetab/config.json`).
-4. **Phase 4 — MCP Auto-Config:** Auto-detects installed IDEs (Claude Desktop, Cursor, Windsurf, VS Code, OpenCode, Claude Code, Antigravity) and merges Weavetab into their MCP configuration.
-5. **Phase 5 — Summary:** Displays full configuration validation report.
+1. **Phase 1 — Essentials:** Browser path, RBAC role (`admin`, `viewer`, `automation`), headless mode, dev mode, max tabs, actionability timeout, domain block/allow lists.
+2. **Phase 2 — Advanced (optional):** Browser engine selection, timeouts and rate limits, telemetry opt-in, download/proxy directories, domain policy entries.
+3. **Phase 3 — Save Location:** Global (`~/.weavetab/config.json`).
+4. **Phase 4 — MCP Auto-Config:** Auto-detects installed IDEs (Claude Desktop, Cursor, Windsurf) and merges Weavetab into their MCP configuration.
+5. **Phase 5 — Agent Skills:** Optionally installs `@weavetab/skills` for your agent framework.
+6. **Phase 6 — Summary:** Displays full configuration validation report.

package/docs/intelligence/site-profiles.md

@@ -0,0 +1,151 @@
+---
+title: "Site Profiles and Intelligent Memory"
+description: "Persistent cross-session workflow memory, pattern compilation, and quirk bypass in ~/.weavetab-system/memory/sites/."
+product: mcp
+section: intelligence
+icon: Brain
+slug: site-profiles
+---
+
+# Site Profiles and Intelligent Memory Engine
+
+Every browser automation session normally starts from zero context. The agent re-inspects DOM trees, re-triggers cookie banners, and re-discovers login fields.
+
+Weavetab solves this with a **Two-Tier Persistent Memory System** that accumulates knowledge about domains and workflows across sessions.
+
+---
+
+## Directory Hierarchy: System vs. User Space
+
+| Directory | Purpose | Managed By |
+| :--- | :--- | :--- |
+| `~/.weavetab-system/memory/sites/` | **Persistent Site Profiles**: named workflow patterns, quirks, reliability scores | Weavetab Engine (autonomous) |
+| `~/.weavetab-system/memory/` | **Selector Confidence Cache**: per-domain element selectors and strike counters | Weavetab Engine (autonomous) |
+| `~/.weavetab-system/sessions/` | **Rolling Action Trails**: 50-step window for loop detection | Weavetab Engine (autonomous) |
+| `~/.weavetab/` | **User Configuration**: `config.json`, `secrets.json`, `policy.json`, plugins | User / Developer (manual) |
+
+> **Directory Law**: Machine-compiled memory profiles are strictly located in `~/.weavetab-system/memory/sites/`. User configuration in `~/.weavetab/` is never polluted by machine learning trails or dynamic decay counters.
+
+---
+
+## Site Profile Schema
+
+Profiles are stored as `<sanitized-hostname>.json` under `~/.weavetab-system/memory/sites/`:
+
+```json
+{
+  "origin": "https://github.com",
+  "framework": "react",
+  "shadowDom": false,
+  "captcha_frequency": "rare",
+  "quirks": {
+    "cookie_banner": {
+      "selector": "#cookie-consent",
+      "action": "click .accept-all",
+      "appears": "first_visit"
+    },
+    "rate_limit": {
+      "threshold": "60req/min",
+      "recovery": "wait 30s"
+    }
+  },
+  "patterns": {
+    "login_flow": {
+      "name": "login_flow",
+      "steps": [
+        { "tool": "browser_navigate", "target": "https://github.com/login" },
+        { "tool": "browser_fill", "target": "#login_field", "value": "{{username}}" },
+        { "tool": "browser_fill", "target": "#password", "value": "{{password}}" },
+        { "tool": "browser_click", "target": "[type=submit]" }
+      ],
+      "success_indicator": "a[aria-label='Homepage']",
+      "entry": "/login",
+      "avg_duration_ms": 3200,
+      "reliability": 0.96,
+      "strikes": 0,
+      "last_verified": "2026-09-16T08:00:00.000Z",
+      "total_executions": 12,
+      "successful_executions": 12
+    }
+  },
+  "visitCount": 15,
+  "updatedAt": "2026-09-16T08:00:00.000Z"
+}
+```
+
+---
+
+## The Pattern Compiler
+
+When an agent executes an automation flow:
+1. **Trail Capture**: Steps are tracked via the lightweight action trail.
+2. **Selector Stabilization**: Volatile CSS hash classes (`[class*="hash-"]`), positional pseudos (`:nth-child`), and deep anonymous structural chains are filtered out. Only semantic selectors (`id`, `data-testid`, semantic attributes, roles) are persisted.
+3. **Merge-on-Write**: Calling `browser_pattern_learn` updates existing patterns in place. Duplicate calls never create duplicate files or duplicate entries.
+4. **Anti-Spam Guard**: If an incoming pattern is identical to stored disk state, the disk write is skipped entirely.
+
+---
+
+## Reliability Scoring and 3-Strike Degradation
+
+Each pattern tracks a reliability score (`0.0` to `1.0`) computed via Exponentially Weighted Moving Average (EWMA with $\alpha = 0.15$):
+
+$$\text{Reliability}_{t} = 0.85 \times \text{Reliability}_{t-1} + 0.15 \times (\text{Success} ? 1 : 0)$$
+
+### Decision Thresholds
+
+- **Fast-Path ($\ge 0.80$)**: Replay stored steps directly via `browser_burst` — skips exploratory DOM navigation entirely.
+- **Cautious Replay ($0.50 - 0.79$)**: Replay steps, but verify `success_indicator` after critical steps.
+- **Re-Learn ($< 0.50$ or $\ge 3$ consecutive strikes)**: Pattern is flagged `[RE-LEARN NEEDED]`. The agent falls back to fresh DOM exploration, then calls `browser_pattern_learn` to teach the updated steps.
+
+---
+
+## MCP Tools
+
+### `browser_pattern_learn`
+All site memory operations use a single tool. Use `action: "get"` to read a site profile, `action: "learn"` to register a workflow, `action: "record_execution"` to update reliability scores, and `action: "record_quirk"` to store site quirks:
+
+```json
+{ "action": "get", "origin": "https://github.com" }
+```
+
+```json
+{
+  "origin": "https://github.com",
+  "action": "learn",
+  "name": "login_flow",
+  "steps": [
+    { "tool": "browser_click", "target": ".btn-login" },
+    { "tool": "browser_fill", "target": "#login_field", "value": "{{username}}" }
+  ],
+  "success_indicator": "a[aria-label='Homepage']"
+}
+```
+
+---
+
+## SDK Plugin Integration (`ctx.memory`)
+
+Plugin authors can interact with persistent site memory directly via the SDK:
+
+```typescript
+import { definePlugin } from "@weavetab/sdk";
+
+export default definePlugin({
+  name: "custom-site-automator",
+  async onLoad(ctx) {
+    // Read current profile
+    const profile = await ctx.memory?.getSiteProfile("https://github.com");
+
+    // Check reliability
+    const reliability = await ctx.memory?.getReliability("https://github.com", "login_flow");
+    if (reliability && reliability >= 0.8) {
+      ctx.logger.info("Fast-path ready for login_flow");
+    }
+
+    // Teach a new pattern
+    await ctx.memory?.learnPattern("https://github.com", "quick_search", {
+      steps: [{ tool: "browser_fill", target: "input.header-search-input", value: "test" }]
+    });
+  }
+});
+```