@weavetab/skills 1.0.3 → 2.5.0-beta.4

package/dist/bundled/weavetab-network-and-perf.md

@@ -0,0 +1,223 @@
+# Weavetab Domain Profile: NETWORK-AND-PERF
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## device-and-environment
+
+# Device Emulation & Environment Simulation
+
+Auditing mobile responsive layouts, testing geographic restrictions, and simulating degraded network conditions can all be accomplished with `browser_emulate`.
+
+---
+
+## 1. Device Presets & Viewport Simulation
+
+Switch from desktop to realistic mobile hardware profiles:
+
+```json
+{
+  "device": "iPhone 15 Pro",
+  "orientation": "portrait"
+}
+```
+
+Or configure custom screen geometries:
+
+```json
+{
+  "viewport": {
+    "width": 393,
+    "height": 852,
+    "deviceScaleFactor": 3,
+    "isMobile": true,
+    "hasTouch": true
+  }
+}
+```
+
+---
+
+## 2. Network Throttling Simulation
+
+Verify how web applications degrade under poor connectivity:
+
+```json
+{
+  "network": {
+    "offline": false,
+    "downloadThroughput": 1024 * 500, // 500 kb/s (Slow 3G)
+    "uploadThroughput": 1024 * 250,
+    "latency": 400 // ms
+  }
+}
+```
+
+---
+
+## 3. Geolocation & Timezone Overrides
+
+Bypass localized IP redirects or verify localized content rendering:
+
+```json
+{
+  "geolocation": {
+    "latitude": 37.7749,
+    "longitude": -122.4194,
+    "accuracy": 100
+  },
+  "timezoneId": "America/Los_Angeles",
+  "locale": "en-US"
+}
+```
+
+To reset all overrides back to default host system parameters:
+```json
+{
+  "reset": true
+}
+```
+
+
+## network-intercept-and-mock
+
+# Network Interception, Mocking & TLS Forensics
+
+Autonomous testing and debugging often require simulating backend error states (e.g. 500 Internal Server Error, 429 Rate Limit), stubbing third-party analytics, or verifying TLS/SSL certificates.
+
+`browser_network_intercept` provides fine-grained CDP request and response modification.
+
+---
+
+## 1. Mocking API Responses
+
+Intercept outgoing HTTP requests matching a URL pattern and return custom mock data:
+
+```json
+{
+  "pattern": "*/api/v1/user/profile",
+  "response": {
+    "status": 200,
+    "headers": {
+      "Content-Type": "application/json"
+    },
+    "body": "{\"id\": \"usr_test\", \"role\": \"admin\", \"credits\": 9999}"
+  }
+}
+```
+
+---
+
+## 2. Blocking Unnecessary Traffic & Trackers
+
+Accelerate page loads and eliminate token bloat by aborting non-essential requests:
+
+```json
+{
+  "pattern": "*google-analytics.com*",
+  "action": "abort",
+  "errorReason": "BlockedByClient"
+}
+```
+
+---
+
+## 3. TLS / SSL Forensics & Timing Waterfalls
+
+Extract cryptographic handshake metadata, cipher suites, expiration dates, and microsecond network waterfalls (DNS lookup, TCP connect, SSL handshake, TTFB):
+
+```json
+{
+  "action": "auditTls",
+  "url": "https://weavetab.pages.dev"
+}
+```
+
+### Response Example:
+```json
+{
+  "security": {
+    "protocol": "TLS 1.3",
+    "cipher": "AES_128_GCM",
+    "issuer": "Let's Encrypt",
+    "validTo": "2026-11-15T00:00:00.000Z"
+  },
+  "waterfall": {
+    "dnsMs": 1.4,
+    "tcpMs": 3.2,
+    "sslMs": 4.1,
+    "ttfbMs": 12.8
+  }
+}
+```
+
+
+## performance-and-vitals
+
+# Performance Forensics & Core Web Vitals
+
+Optimizing agent execution and auditing client performance requires objective metrics rather than arbitrary sleep timers.
+
+---
+
+## 1. Core Web Vitals Auditing (`browser_performance`)
+
+Retrieve Google Core Web Vitals, memory consumption, and frame rendering bottlenecks directly from the Chromium engine:
+
+```json
+{
+  "metrics": ["vitals", "memory", "navigationTiming"]
+}
+```
+
+### Response Example:
+```json
+{
+  "vitals": {
+    "fcp": 320,
+    "lcp": 780,
+    "cls": 0.012,
+    "fid": 8,
+    "inp": 45
+  },
+  "memory": {
+    "jsHeapUsedSizeMb": 42.1,
+    "jsHeapTotalSizeMb": 68.4
+  }
+}
+```
+
+---
+
+## 2. Deterministic Synchronization (`browser_wait`)
+
+> [!WARNING]
+> NEVER call arbitrary fixed sleep timers (e.g. `sleep 5000`). Fixed sleeps waste user time and still fail when network latency spikes.
+
+Always synchronize with deterministic browser conditions:
+
+### Wait for Network Idle:
+```json
+{
+  "condition": "network_idle",
+  "timeout": 10000
+}
+```
+
+### Wait for DOM Mutation Stability:
+```json
+{
+  "condition": "dom_stable",
+  "duration": 500,
+  "timeout": 10000
+}
+```
+
+### Wait for a Specific Element to Appear:
+```json
+{
+  "condition": "element_visible",
+  "selector": "[data-testid=\"checkout-complete\"]",
+  "timeout": 15000
+}
+```

package/dist/bundled/weavetab-plugins.md

@@ -0,0 +1,78 @@
+# Weavetab Domain Profile: PLUGINS
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## hooks-and-overrides
+
+# Plugin Hooks & Lifecycle Overrides
+
+Plugins built with `@weavetab/sdk` register lifecycle hooks that run before and after tool executions. Understanding these hooks helps agents interpret metadata and custom tool responses.
+
+---
+
+## 1. Supported Plugin Hooks
+
+1. **`beforeToolCall(toolName, args)`**:
+   - Validates arguments against custom enterprise schemas.
+   - Injects tenant IDs, authentication headers, or proxy routing.
+2. **`afterToolCall(toolName, result, durationMs)`**:
+   - Emits OpenTelemetry metrics and timing waterfalls to external APM platforms.
+   - Enriches return objects with contextual metadata.
+3. **`onNavigate(url, targetId)`**:
+   - Triggers automated cookie injection or session setup upon page navigation.
+
+---
+
+## 2. Agent Operational Awareness
+
+When plugins are active, tool return payloads may include an optional `_pluginMetadata` object containing trace IDs, custom metrics, or security audit timestamps. Agents should treat this object as informational telemetry.
+
+
+## plugin-runtime
+
+# Plugin Runtime: Dynamic Extension Loading
+
+Weavetab features an extensible plugin architecture powered by `@weavetab/sdk`. Agents can query loaded extensions and dynamically load community or official plugins into the live MCP runtime without restarting the server.
+
+---
+
+## 1. Inspecting Active Plugins (`list_plugins`)
+
+Discover all installed plugins, their versions, and the tools or hooks they expose:
+
+```json
+{}
+```
+
+### Response Example:
+```json
+{
+  "plugins": [
+    {
+      "name": "@weavetab/plugin-recaptcha-solver",
+      "version": "1.2.0",
+      "status": "active",
+      "toolsProvided": ["captcha_solve_token"],
+      "hooks": ["beforeToolCall"]
+    }
+  ]
+}
+```
+
+---
+
+## 2. Dynamic Runtime Loading (`load_plugin`)
+
+Load a verified plugin package into the active runtime session:
+
+```json
+{
+  "name": "@weavetab/plugin-datadog-tracer"
+}
+```
+
+### Plugin Verification Guarantees:
+- Plugins must implement the `@weavetab/sdk` standard interface.
+- Loaded tools become immediately callable by the agent in subsequent turns.
+- If an agent is in the `viewer` RBAC tier, `load_plugin` is rejected with `PERMISSION_DENIED`.

package/dist/bundled/weavetab-resilience.md

@@ -0,0 +1,216 @@
+# Weavetab Domain Profile: RESILIENCE
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## loop-breaker
+
+# Loop Breaker & CAPTCHA Escalation Protocol
+
+Agents can get trapped in repetitive click loops when a button does not advance the state (e.g. failing silent validation, unhandled reCAPTCHA challenges, or modals swallowing events). Weavetab actively monitors repetitive patterns and provides circuit breakers.
+
+---
+
+## 1. Loop Detection & Strike Reset (`browser_map`)
+
+Weavetab tracks the sequence of identical or near-identical tool invocations. If an agent calls `browser_click` or `browser_type` on the same selector or ref repeatedly without URL or major DOM mutations, the server raises a `STUCK_LOOP_WARNING`.
+
+### How to Break the Loop:
+1. **Analyze Why the Action Failed**: Check `browser_console` for JavaScript errors:
+   ```json
+   { "action": "read" }
+   ```
+   Or use `browser_map` to see if a validation banner or unhandled modal appeared.
+2. **Reset the Circuit Breaker**:
+   - Re-map with `force: true` to bypass the map skip guard, refresh the DOM view, and automatically clear loop strikes:
+     ```json
+     { "force": true }
+     ```
+
+---
+
+## 2. CAPTCHA Handling Protocol (`browser_captcha`)
+
+When an automated flow is blocked by Cloudflare Turnstile, Google reCAPTCHA, or hCaptcha, do NOT repeatedly click random coordinates.
+
+Invoke `browser_captcha` to analyze and manage the challenge:
+
+```json
+{
+  "action": "detect"
+}
+```
+
+### Response Example:
+```json
+{
+  "detected": true,
+  "type": "turnstile",
+  "provider": "cloudflare",
+  "interactive": true,
+  "ref": "w:99"
+}
+```
+
+### Action Strategy:
+1. If the challenge is interactive and requires human intervention (e.g. image classification), inform the user cleanly or request human bypass.
+2. If the challenge is a simple checkbox Turnstile widget, pass `"action": "solve"` or click the detected widget ref with `browser_click`.
+
+
+## session-time-travel
+
+# Session Time-Travel & Instant State Rollback
+
+In complex multi-step workflows (e.g. checkout funnels, multi-page configuration wizards, onboarding questionnaires), an error at Step 7 traditionally forces an agent to reload the root URL, re-authenticate, and waste 10+ turns repeating steps.
+
+`browser_checkpoint` enables instantaneous time-travel by snapshotting and restoring complete browser session state.
+
+---
+
+## 1. What a Checkpoint Captures
+
+A single named checkpoint atomically preserves:
+- **Cookies**: Full domain cookies including `HttpOnly`, `Secure`, and `SameSite` flags.
+- **Web Storage**: Entire `localStorage` and `sessionStorage` key-value maps.
+- **Navigation State**: Exact page URL, scroll positions (`x`, `y`), and page title.
+
+---
+
+## 2. Checkpoint Operations
+
+### A. Saving a Checkpoint (`save`)
+Create a checkpoint right before undertaking risky, branching, or destructive actions:
+
+```json
+{
+  "action": "save",
+  "name": "pre_checkout_authenticated"
+}
+```
+
+### B. Restoring a Checkpoint (`restore`)
+If a downstream step errors out, times out, or hits an invalid state, roll back immediately:
+
+```json
+{
+  "action": "restore",
+  "name": "pre_checkout_authenticated"
+}
+```
+*Latency: ~15ms*. The page navigates back to the checkpoint URL with cookies and storage atomically injected.
+
+### C. Listing Checkpoints (`list`)
+Inspect all active checkpoints for the current page target:
+
+```json
+{
+  "action": "list"
+}
+```
+
+### D. Cleaning Up (`delete`)
+Free memory once a workflow has concluded:
+
+```json
+{
+  "action": "delete",
+  "name": "pre_checkout_authenticated"
+}
+```
+
+---
+
+## 3. High-Leverage Agent Pattern
+
+```
+1. Authenticate to Target Portal
+2. browser_checkpoint({ action: "save", name: "auth_ready" })
+3. Attempt automated action sequence (e.g. form filling or testing)
+4. IF error occurs:
+     browser_checkpoint({ action: "restore", name: "auth_ready" })
+     -> Agent is immediately back at authenticated state without re-login!
+```
+
+---
+
+## 4. Fine-Grained Cookie Management (`browser_cookies`)
+
+Inspect, set, or delete individual browser session cookies without restoring an entire checkpoint:
+
+```json
+{
+  "action": "get",
+  "urls": ["https://example.com"]
+}
+```
+
+Or inject an authentication cookie:
+```json
+{
+  "action": "set",
+  "cookies": [
+    {
+      "name": "session_token",
+      "value": "xyz123",
+      "domain": "example.com",
+      "httpOnly": true,
+      "secure": true
+    }
+  ]
+}
+```
+
+---
+
+## 5. Web Storage Inspection & Injection (`browser_storage`)
+
+Query or clear `localStorage` and `sessionStorage` keys:
+
+```json
+{
+  "storageType": "localStorage",
+  "action": "get",
+  "key": "authToken"
+}
+```
+
+
+## stale-ref-recovery
+
+# Stale Ref Recovery & SPA Hydration Resilience
+
+In modern Single Page Applications (built with React, Next.js, Vue, Nuxt, Svelte), DOM nodes are frequently destroyed and recreated during client-side hydration or reactive state updates. This often causes `STALE_ELEMENT_REFERENCE` or `NODE_DETACHED` errors when an agent attempts an action.
+
+---
+
+## 1. The 4-Tier Auto-Recovery Chain
+
+When a tool receives a stale or missing `ref`, Weavetab does not immediately fail. It activates an internal 4-tier recovery chain:
+
+```
+  [Action on w:14 Fails / Stale]
+                │
+                ▼
+  [Tier 1: Stored Selector] ──▶ Re-queries cached stable selector (data-testid, id)
+                │ (if not found)
+                ▼
+  [Tier 2: Exact Label Match] ──▶ Queries element with identical visible text & tag
+                │ (if not found)
+                ▼
+  [Tier 3: Semantic Role Match] ──▶ Queries nearest sibling with matching ARIA role
+                │ (if not found)
+                ▼
+  [Tier 4: Fuzzy Match] ──▶ Re-anchors to highest-confidence visual candidate
+```
+
+If the recovery chain succeeds, the action executes seamlessly and the return payload notifies the agent that the handle was refreshed.
+
+---
+
+## 2. Agent Reactive Behavior
+
+If an action returns `ERROR: STALE_ELEMENT_REFERENCE` because all 4 recovery tiers were exhausted:
+
+1. **Do NOT Repeat the Identical Call**: Retrying the exact same stale `ref` (`w:14`) will fail again.
+2. **Execute a Fast Targeted Lookup**: Run `browser_find` with the text of the button or input field.
+3. **Execute the Action on the New Handle**: Use the updated handle returned by `browser_find`.

package/dist/bundled/weavetab-security.md

@@ -0,0 +1,87 @@
+# Weavetab Domain Profile: SECURITY
+
+Generated for @weavetab/skills v2.5.0-beta.4
+
+
+## rbac-and-policies
+
+# Role-Based Access Control (RBAC) & Agent Guardrails
+
+Weavetab allows developers to run untrusted or lower-privilege subagents within strict security boundaries to prevent accidental destructive operations or data leaks.
+
+---
+
+## 1. The 4 Security Tiers
+
+| Tier | Name | Allowed Tools & Capabilities | Intended Role |
+| :--- | :--- | :--- | :--- |
+| **0** | `admin` | Full tool access (all 48 tools), plugin loading, arbitrary script eval, cookies/storage write. | Primary Operator / Lead Agent. |
+| **1** | `operator` | Interactive tools (`browser_click`, `browser_fill`, `browser_upload`), but blocked from loading untrusted plugins. | Standard Automation Agent. |
+| **2** | `automation` | Pre-approved deterministic macros (`browser_automation`), scoped form filling, no arbitrary script execution. | Background Cron / Worker. |
+| **3** | `viewer` | Read-only inspection tools (`browser_map`, `browser_find`, `browser_scrape`, `browser_inspect`). All click, type, and storage tools are rejected with `PERMISSION_DENIED`. | Research Subagents / Scrapers. |
+
+---
+
+## 2. Handling `PERMISSION_DENIED` Errors
+
+If an agent attempts an action outside its allocated role tier:
+```json
+{
+  "error_code": "PERMISSION_DENIED",
+  "message": "Tool 'browser_click' is disabled under role 'viewer'. Only read operations are permitted."
+}
+```
+
+### Protocol:
+1. Do not retry the denied tool.
+2. Delegate the interactive action to the parent agent or primary operator.
+3. Limit your output to findings gathered via read-only tools (`browser_scrape`, `browser_map`, `browser_inspect`).
+
+
+## secret-containment-protocol
+
+# Secret Containment Protocol & Zero-Bleed Execution
+
+AI agent transcripts, LLM providers, and tool logs represent massive attack surfaces for credential leaks. Weavetab enforces a hardware-grade **Zero-Bleed Security Guarantee** for sensitive inputs.
+
+---
+
+## 1. Entering Credentials with `browser_type_secret`
+
+Whenever an agent inputs passwords, two-factor backup codes, credit card numbers, or proprietary API keys, you MUST use `browser_type_secret`:
+
+```json
+{
+  "ref": "w:12",
+  "secret": "MySuperSecretPassword!2026",
+  "clear": true
+}
+```
+
+---
+
+## 2. The Zero-Bleed Guarantee Architecture
+
+When `browser_type_secret` is invoked:
+1. **CDP Interception**: The secret is typed via masked CDP synthetic key events.
+2. **HUD Redaction**: The browser Heads-Up Display (HUD) and visual overlay strictly renders bullets (`••••••••`).
+3. **Log Sanitization**: Console logs, MCP server logs, and JSON return values strip the secret string and return:
+   ```json
+   {
+     "success": true,
+     "message": "Secret typed successfully into ref 'w:12' (length: 26). Value redacted."
+   }
+   ```
+4. **No Re-Emission**: Never print or echo raw credentials into subsequent model thoughts or conversation messages.
+
+---
+
+## 3. Strict Operating Prohibition
+
+> [!CAUTION]
+> Under NO circumstances should an agent pass passwords or credentials to:
+> - `browser_type`
+> - `browser_fill`
+> - `browser_eval`
+> 
+> Doing so causes plaintext secrets to enter unmasked transcripts and tool logs.