@weavetab/skills 2.5.0 → 2.5.1

package/dist/bundled/weavetab-resilience.md

@@ -1,216 +1,244 @@
-# Weavetab Domain Profile: RESILIENCE
-
-Generated for @weavetab/skills v2.5.0-beta.5
-
-
-## 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`.
+# Weavetab Domain Profile: RESILIENCE
+
+Generated for @weavetab/skills v2.5.1
+
+
+## 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
+{
+  "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.
+
+
+## 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",
+  "url": "https://example.com"
+}
+```
+
+Or inject an authentication cookie (one cookie per call):
+
+```json
+{
+  "action": "set",
+  "name": "session_token",
+  "value": "xyz123",
+  "domain": "example.com",
+  "path": "/",
+  "httpOnly": true,
+  "secure": true,
+  "sameSite": "Lax"
+}
+```
+
+Delete a cookie by name (and optionally domain/path):
+
+```json
+{
+  "action": "delete",
+  "name": "session_token",
+  "domain": "example.com"
+}
+```
+
+Accepted fields: `name`, `value`, `domain`, `path`, `expires` (Unix seconds), `httpOnly`, `secure`, `sameSite` (`Strict`/`Lax`/`None`), and `url` (for `get`).
+
+---
+
+## 5. Web Storage Inspection & Injection (`browser_storage`)
+
+Query or clear `localStorage` and `sessionStorage` keys. Choose the store with `scope`:
+
+```json
+{
+  "scope": "local",
+  "action": "get",
+  "key": "authToken"
+}
+```
+
+- **`scope`**: `"local"` or `"session"`.
+- **`action`**: `get`, `set`, `remove`, `list` (all keys + values), or `clear` (the whole scope).
+- **`key`** is required for `get`, `set`, and `remove`; **`value`** is required for `set`.
+
+
+## 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 can invalidate a volatile `w:NN` handle between reads and actions.
+
+---
+
+## 1. The Multi-Tier Auto-Recovery Heuristic
+
+When a tool receives a detached or invalidated `ref`, Weavetab attempts to re-resolve it instead of failing immediately. The recovery runs a sub-5ms heuristic over these strategies (in order) and re-stamps `data-wt-id="NN"` onto the live node:
+
+```
+  [Action on w:14 fails / handle detached]
+                 │
+                 ▼
+  [1. Connected node + fingerprint check]
+                 │ (if not found)
+                 ▼
+  [2. Stored CSS selector]  (data-testid, id, class)
+                 │ (if not found)
+                 ▼
+  [3. Exact label / aria-label match]
+                 │ (if not found)
+                 ▼
+  [4. Placeholder / name attribute match]
+                 │ (if not found)
+                 ▼
+  [5. Fuzzy substring match]  (when label length >= 3)
+```
+
+The successful strategy is reported back to the agent (`stored_selector`, `exact_label`, `placeholder_or_name`, `fuzzy_label`). If every strategy misses, the tool returns a hard failure.
+
+---
+
+## 2. Agent Reactive Behavior
+
+If an action fails because all recovery strategies were exhausted, the tool returns one of:
+
+- `error_code: "ELEMENT_NOT_FOUND"` — the ref was in the cached map but no longer exists in the DOM.
+- `error_code: "FINGERPRINT_MISMATCH"` — an element exists but its tag/role fingerprint no longer matches; the DOM was likely rebuilt.
+
+Either way:
+
+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, or refresh handles with `browser_map`.
+3. **Execute the Action on the New Handle**: use the updated ref returned by `browser_find`/`browser_map`.

package/dist/bundled/weavetab-security.md

@@ -1,87 +1,93 @@
-# Weavetab Domain Profile: SECURITY
-
-Generated for @weavetab/skills v2.5.0-beta.5
-
-
-## 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.
+# Weavetab Domain Profile: SECURITY
+
+Generated for @weavetab/skills v2.5.1
+
+
+## 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.
+
+Roles are configured per agent (in `config.json`). The server checks the role **before** launching a browser or resolving the target.
+
+---
+
+## 1. The 5 Security Roles
+
+| Role | Tool Access | Intended Use |
+| :--- | :--- | :--- |
+| `admin` | Full access (`*`). | Primary operator / lead agent. |
+| `operator` | Full access (`*`). | Standard automation agent. |
+| `automation` | Every tool except `browser_thoughts` — automation agents must be non-interactive. | Background cron / worker. |
+| `viewer` | Read-only set only: `browser_map`, `browser_find`, `browser_scrape`, `browser_console`, `browser_eval`, `browser_inspect`, `browser_extract_design`, `browser_snapshot`, `browser_screenshot`, `browser_pdf`, `browser_cookies`, `browser_tabs`, `browser_wait`, `browser_pattern_learn`. | Research subagents / scrapers. |
+| `system` | `browser_thoughts`, `browser_detect`, `browser_performance`, `browser_checkpoint`, `browser_pattern_learn`. | Internal/system operations. |
+
+Any other role value is treated as fully allowed.
+
+---
+
+## 2. Handling Permission Denials
+
+There is no JSON `error_code` for RBAC. A denied call fails with `isError: true` and a plain-text message prefixed with `[!]`:
+
+```
+[!] Role 'viewer' does not have permission to use 'browser_click'. Viewer role only permits read-only tools (map/find/scrape/console/eval/inspect/snapshot/pdf/cookies).
+```
+
+### Protocol:
+1. Do not retry the denied tool — the role will not change mid-session.
+2. Delegate the interactive action to the parent agent or a higher-privilege 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`.
+
+`browser_type_secret` never accepts a plaintext secret. It reads the value from an **environment variable** on the host running the MCP server, so the secret never reaches the agent transcript. Set the variable first (e.g. `export PORTAL_PASSWORD="…"`), then reference it by key:
+
+```json
+{
+  "ref": "w:12",
+  "envKey": "PORTAL_PASSWORD"
+}
+```
+
+Accepted targeting parameters: `id` (alias `ref`) or `target` (CSS selector). `envKey` is **required**.
+
+---
+
+## 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.