@weavetab/skills 2.5.0 → 2.5.2

package/dist/granular/network-and-perf_performance-and-vitals.md

@@ -1,84 +1,86 @@
----
-id: performance-and-vitals
-domain: network-and-perf
-triggers:
-  - "measure performance"
-  - "core web vitals"
-  - "lcp"
-  - "cls"
-  - "fcp"
-  - "wait condition"
-  - "page slow"
-tools:
-  - "browser_performance"
-  - "browser_wait"
-weavetab: ">=2.5.0-beta.5"
----
-
-# 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
-}
-```
+---
+id: performance-and-vitals
+domain: network-and-perf
+triggers:
+  - "measure performance"
+  - "core web vitals"
+  - "lcp"
+  - "cls"
+  - "fcp"
+  - "wait condition"
+  - "page slow"
+tools:
+  - "browser_performance"
+  - "browser_wait"
+weavetab: ">=2.5.0"
+---
+
+# 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", "navigation"]
+}
+```
+
+### Response Example:
+```json
+{
+  "vitals": {
+    "fcp": 320,
+    "lcp": 780,
+    "cls": 0.012,
+    "inp": 45,
+    "ttfb": 12
+  },
+  "memory": {
+    "usedJSHeapSize": 44154880,
+    "totalJSHeapSize": 71729152,
+    "jsHeapSizeLimit": 4294705152
+  }
+}
+```
+
+Valid `metrics` sections: `"vitals"`, `"memory"`, `"navigation"`, `"resources"`, `"raw"`. Omit `metrics` to return all sections. Heap sizes are in **bytes**. The `"resources"` section populates `slowest_resources` (top 10 by duration).
+
+---
+
+## 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
+{
+  "for": "network",
+  "timeout": 10000
+}
+```
+
+### Wait for DOM Mutation Stability:
+```json
+{
+  "for": "stable",
+  "timeout": 10000
+}
+```
+
+### Wait for a Specific Element to Appear:
+```json
+{
+  "for": "element",
+  "value": "[data-testid=\"checkout-complete\"]",
+  "timeout": 15000
+}
+```

package/dist/granular/plugins_hooks-and-overrides.md

@@ -1,35 +1,40 @@
----
-id: hooks-and-overrides
-domain: plugins
-triggers:
-  - "plugin hooks"
-  - "before tool call"
-  - "after tool call"
-  - "telemetry interception"
-  - "sdk hooks"
-tools: []
-weavetab: ">=2.5.0-beta.5"
----
-
-# 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.
+---
+id: hooks-and-overrides
+domain: plugins
+triggers:
+  - "plugin hooks"
+  - "before tool call"
+  - "after tool call"
+  - "telemetry interception"
+  - "sdk hooks"
+tools: []
+weavetab: ">=2.5.0"
+---
+
+# 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 custom tool behavior and blocked actions.
+
+---
+
+## 1. Supported Plugin Hooks
+
+The `PluginHooks` interface exposes three primary interceptors (with backwards-compatible aliases):
+
+1. **`onBeforeAction(handler)`** — *alias:* `beforeToolCall`
+   - `handler(tool, args, session)` runs **before** any tool executes.
+   - It may return a modified `args` object (replacing the arguments) or `{ __blocked: true, reason }` to abort the call.
+   - Typical uses: argument validation, tenant/header injection, proxy routing.
+2. **`onAfterAction(handler)`** — *alias:* `afterToolCall`
+   - `handler(tool, result, session, args)` runs **after** a tool completes.
+   - Its return value replaces the tool result — used for telemetry, timing, or enriching output.
+3. **`onDOMMutation(handler)`** — *alias:* `onPageNavigate`
+   - `handler(delta, session)` observes real-time DOM mutation / action deltas (added, removed, and changed elements, `significantChange`, `stable_count`).
+
+---
+
+## 2. Agent Operational Awareness
+
+- A blocked action surfaces as a normal tool error (the server turns `__blocked` into an error result). If a plugin blocks a tool you expected to succeed, do not retry it blindly — report the block reason and pick another approach.
+- An `onAfterAction` handler can rewrite a tool's result. Treat the returned payload as authoritative, not a fixed schema.
+- Plugins never inject plaintext secrets into results; the Redaction Layer runs on all error output (`SessionSecretTracker.redactAll`).

package/dist/granular/plugins_plugin-runtime.md

@@ -1,63 +1,63 @@
----
-id: plugin-runtime
-domain: plugins
-triggers:
-  - "what plugins are installed"
-  - "weavetab plugin"
-  - "extend mcp"
-  - "plugin tools"
-  - "plugin permissions"
-tools: []
-weavetab: ">=2.5.0-beta.5"
----
-
-# Plugin Runtime: Weavetab Plugin Architecture
-
-Weavetab features an extensible plugin architecture powered by `@weavetab/sdk`. All installed plugins are loaded automatically at server startup — their tools appear directly in the MCP tool list alongside built-in tools. Agents never need to discover or activate plugins manually.
-
----
-
-## 1. How Plugin Tools Appear
-
-Plugin tools are first-class MCP tools. If `@weavetab/plugin-recaptcha-solver` is installed, `captcha_solve_token` appears in the tool list immediately on startup — no discovery step needed.
-
-There are **no** `list_plugins` or `load_plugin` tools. Managing plugins is a CLI operation:
-
-```bash
-# Install a plugin (restart required)
-weavetab plugin add @weavetab/plugin-youtube
-
-# Remove a plugin
-weavetab plugin rm @weavetab/plugin-youtube
-
-# List installed plugins
-weavetab plugin list
-```
-
----
-
-## 2. Plugin Permission Model
-
-Every plugin declares what it can do in `weavetab.json`. The runtime enforces this at load time:
-
-| Permission | What it gates |
-|---|---|
-| `tools.add: true` | Plugin can register new MCP tools |
-| `tools.override: ["browser_navigate"]` | Plugin can wrap/replace that built-in tool |
-| `tools.remove: ["browser_pdf"]` | Plugin can disable that built-in tool |
-| `hooks.onBeforeAction: true` | Plugin can intercept all tool calls before execution |
-| `hooks.onAfterAction: true` | Plugin can inspect/transform all tool results |
-
-Plugins that attempt to exceed their declared permissions are blocked with a stderr warning — they do not crash.
-
----
-
-## 3. Trust Tiers
-
-| Tier | Badge | Condition |
-|---|---|---|
-| Official | `✚ [Official]` | `@weavetab/plugin-*` packages |
-| Verified | `✔ [Verified]` | Listed in the Weavetab verified registry |
-| Unverified | `⚠ [Unverified]` | Unknown community package |
-
-Unverified plugins are loaded but their permissions are logged visibly at startup for user review.
+---
+id: plugin-runtime
+domain: plugins
+triggers:
+  - "what plugins are installed"
+  - "weavetab plugin"
+  - "extend mcp"
+  - "plugin tools"
+  - "plugin permissions"
+tools: []
+weavetab: ">=2.5.0"
+---
+
+# Plugin Runtime: Weavetab Plugin Architecture
+
+Weavetab features an extensible plugin architecture powered by `@weavetab/sdk`. All installed plugins are loaded automatically at server startup — their tools appear directly in the MCP tool list alongside built-in tools. Agents never need to discover or activate plugins manually.
+
+---
+
+## 1. How Plugin Tools Appear
+
+Plugin tools are first-class MCP tools. If `@weavetab/plugin-recaptcha-solver` is installed, `captcha_solve_token` appears in the tool list immediately on startup — alongside built-ins such as `browser_snapshot` — with no discovery step needed.
+
+There is no MCP tool for discovering or activating plugins. Managing plugins is a CLI operation:
+
+```bash
+# Install a plugin (restart required)
+weavetab plugin add @weavetab/plugin-youtube
+
+# Remove a plugin
+weavetab plugin rm @weavetab/plugin-youtube
+
+# List installed plugins
+weavetab plugin list
+```
+
+---
+
+## 2. Plugin Permission Model
+
+Every plugin declares what it can do in `weavetab.json`. The runtime enforces this at load time:
+
+| Permission | What it gates |
+|---|---|
+| `tools.add: true` | Plugin can register new MCP tools |
+| `tools.override: ["browser_navigate"]` | Plugin can wrap/replace that built-in tool |
+| `tools.remove: ["browser_pdf"]` | Plugin can disable that built-in tool |
+| `hooks.onBeforeAction: true` | Plugin can intercept all tool calls before execution |
+| `hooks.onAfterAction: true` | Plugin can inspect/transform all tool results |
+
+Plugins that attempt to exceed their declared permissions are blocked with a stderr warning — they do not crash.
+
+---
+
+## 3. Trust Tiers
+
+| Tier | Badge | Condition |
+|---|---|---|
+| Official | `✚ [Official]` | `@weavetab/plugin-*` packages |
+| Verified | `✔ [Verified]` | Listed in the Weavetab verified registry |
+| Unverified | `⚠ [Unverified]` | Unknown community package |
+
+Unverified plugins are loaded but their permissions are logged visibly at startup for user review.

package/dist/granular/resilience_loop-breaker.md

@@ -1,67 +1,72 @@
----
-id: loop-breaker
-domain: resilience
-triggers:
-  - "loop detected"
-  - "stuck in loop"
-  - "reset loop counter"
-  - "captcha detected"
-  - "hcaptcha"
-  - "recaptcha"
-tools:
-  - "browser_map"
-  - "browser_console"
-  - "browser_captcha"
-weavetab: ">=2.5.0-beta.5"
----
-
-# 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`.
+---
+id: loop-breaker
+domain: resilience
+triggers:
+  - "loop detected"
+  - "stuck in loop"
+  - "reset loop counter"
+  - "captcha detected"
+  - "hcaptcha"
+  - "recaptcha"
+tools:
+  - "browser_map"
+  - "browser_console"
+  - "browser_captcha"
+weavetab: ">=2.5.0"
+---
+
+# 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
+{
+  "success": true,
+  "action": "detect",
+  "captcha_detected": true,
+  "captcha_type": "turnstile",
+  "interaction_type": "checkbox",
+  "difficulty": "easy",
+  "confidence": 0.97,
+  "human_needed": false,
+  "message": "CAPTCHA detected: turnstile (checkbox, 97% confidence)",
+  "next_action": "Call browser_captcha({ action: \"solve\" }) to attempt automated solving."
+}
+```
+
+### Action Strategy:
+1. If `human_needed` is `true` (e.g. image classification), inform the user cleanly or request human bypass — do not guess coordinates.
+2. Otherwise pass `"action": "solve"` to attempt an automated solve (slider drag, hold, checkbox, or invisible challenges). Use `"action": "status"` to check progress and `"action": "wait_for_user"` to pause for human input.