@weavetab/skills 2.5.0 → 2.5.1

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

@@ -1,223 +1,250 @@
-# Weavetab Domain Profile: NETWORK-AND-PERF
-
-Generated for @weavetab/skills v2.5.0-beta.5
-
-
-## 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.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
-}
-```
+# Weavetab Domain Profile: NETWORK-AND-PERF
+
+Generated for @weavetab/skills v2.5.1
+
+
+## device-and-environment
+
+# Device Emulation & Environment Simulation
+
+Auditing mobile responsive layouts, testing geographic restrictions, and simulating degraded network conditions are split across two tools: `browser_viewport` owns device geometry, locale, timezone, and color-scheme emulation; `browser_emulate` owns network throttling and CPU slowdown.
+
+---
+
+## 1. Device Presets & Viewport Simulation (`browser_viewport`)
+
+List the available hardware presets, then apply one:
+
+```json
+{ "action": "list" }
+```
+
+```json
+{
+  "action": "preset",
+  "devicePreset": "iPhone 15 Pro"
+}
+```
+
+Or configure custom screen geometry directly with `action: "set"`:
+
+```json
+{
+  "action": "set",
+  "width": 393,
+  "height": 852,
+  "deviceScaleFactor": 3,
+  "mobile": true,
+  "hasTouch": true,
+  "screenOrientation": "portrait"
+}
+```
+
+Clear all viewport and emulation overrides back to the host defaults:
+
+```json
+{ "action": "clear" }
+```
+
+---
+
+## 2. Network & CPU Throttling (`browser_emulate`)
+
+Verify how web applications degrade under poor connectivity:
+
+```json
+{
+  "network": {
+    "offline": false,
+    "downloadThroughput": 512000,
+    "uploadThroughput": 256000,
+    "latency": 400
+  },
+  "cpuThrottlingRate": 4
+}
+```
+
+Use a named profile for common cases (`"slow3g"`, `"fast3g"`, `"4g"`, `"offline"`, `"online"`):
+
+```json
+{ "network": "slow3g" }
+```
+
+---
+
+## 3. Geolocation, Timezone, Locale & Color Scheme (`browser_viewport`)
+
+Bypass localized IP redirects or verify localized content rendering:
+
+```json
+{
+  "action": "set",
+  "geolocation": {
+    "latitude": 37.7749,
+    "longitude": -122.4194,
+    "accuracy": 100
+  },
+  "timezoneId": "America/Los_Angeles",
+  "locale": "en-US",
+  "colorScheme": "dark"
+}
+```
+
+
+## network-intercept-and-mock
+
+# Network Interception, Mocking & Telemetry
+
+Autonomous testing and debugging often require simulating backend error states (e.g. 500 Internal Server Error, 429 Rate Limit), stubbing third-party analytics, or inspecting real request timing and TLS metadata.
+
+`browser_network_intercept` exposes four actions: `enable`, `disable`, `get_telemetry`, and `clear_telemetry`.
+
+---
+
+## 1. Mocking API Responses (`enable`)
+
+`enable` requires a `pattern` (URL glob). Every matching response is fulfilled with your mock:
+
+```json
+{
+  "action": "enable",
+  "pattern": "*/api/v1/user/profile",
+  "mockStatus": 200,
+  "mockBody": "{\"id\": \"usr_test\", \"role\": \"admin\", \"credits\": 9999}"
+}
+```
+
+- **`pattern`** — URL glob, e.g. `*api/users*`. `*` and `?` are treated as wildcards.
+- **`mockStatus`** — HTTP status to return (default `200`). Use `500`/`429`/`404` to simulate failures.
+- **`mockBody`** — response body string (default `{}`). Pass JSON as a string.
+
+Mocks are served from the extension when present, otherwise via CDP's Fetch domain (fallback mode).
+
+---
+
+## 2. Stopping Interception (`disable`)
+
+Return the browser to live traffic when a test completes:
+
+```json
+{
+  "action": "disable"
+}
+```
+
+---
+
+## 3. Network Telemetry (`get_telemetry`)
+
+`get_telemetry` starts a background capture (if not already running) and returns the recorded requests — including per-request protocol timing phases, TLS/SSL certificate details when the connection exposes them, and failure reasons:
+
+```json
+{
+  "action": "get_telemetry",
+  "pattern": "*api/*"
+}
+```
+
+An optional `pattern` filters the returned requests by URL. The response includes:
+
+```json
+{
+  "success": true,
+  "count": 12,
+  "requests": [
+    {
+      "url": "https://weavetab.dev/api/v1/session",
+      "timing": { "dnsMs": 1.4, "tcpMs": 3.2, "sslMs": 4.1, "ttfbMs": 12.8 }
+    }
+  ],
+  "navigationOccurred": false,
+  "errors": []
+}
+```
+
+> Certificates and timing fields are surfaced only when the underlying connection exposes them; treat missing fields as "not reported", not "absent".
+
+---
+
+## 4. Clearing the Buffer (`clear_telemetry`)
+
+Reset the capture buffer between scenarios without tearing down the session:
+
+```json
+{
+  "action": "clear_telemetry"
+}
+```
+
+
+## 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", "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/bundled/weavetab-plugins.md

@@ -1,83 +1,88 @@
-# Weavetab Domain Profile: PLUGINS
-
-Generated for @weavetab/skills v2.5.0-beta.5
-
-
-## 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: 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.
+# Weavetab Domain Profile: PLUGINS
+
+Generated for @weavetab/skills v2.5.1
+
+
+## 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 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`).
+
+
+## plugin-runtime
+
+# 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.