@weavetab/skills 1.0.3 → 2.5.0-beta.5

package/dist/granular/resilience_session-time-travel.md

@@ -0,0 +1,131 @@
+---
+id: session-time-travel
+domain: resilience
+triggers:
+  - "time travel"
+  - "browser checkpoint"
+  - "rollback session"
+  - "save state"
+  - "restore cookies"
+tools:
+  - "browser_checkpoint"
+  - "browser_cookies"
+  - "browser_storage"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# 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"
+}
+```
+

package/dist/granular/resilience_stale-ref-recovery.md

@@ -0,0 +1,53 @@
+---
+id: stale-ref-recovery
+domain: resilience
+triggers:
+  - "stale element reference"
+  - "detached from dom"
+  - "spa re-render"
+  - "react hydration"
+  - "element not found"
+tools:
+  - "browser_find"
+  - "browser_map"
+  - "browser_click"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# 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/granular/security_rbac-and-policies.md

@@ -0,0 +1,47 @@
+---
+id: rbac-and-policies
+domain: security
+triggers:
+  - "rbac"
+  - "security policy"
+  - "role boundaries"
+  - "viewer agent"
+  - "permission denied"
+tools:
+  - "browser_inspect"
+  - "browser_scrape"
+  - "browser_map"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# 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`).

package/dist/granular/security_secret-containment-protocol.md

@@ -0,0 +1,59 @@
+---
+id: secret-containment-protocol
+domain: security
+triggers:
+  - "enter password"
+  - "input credentials"
+  - "api key entry"
+  - "sensitive token"
+  - "secret containment"
+tools:
+  - "browser_type_secret"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# 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.

package/documents/canvas-and-visual-capture.md

@@ -0,0 +1,103 @@
+---
+id: canvas-and-visual-capture
+domain: documents
+triggers:
+  - "take screenshot"
+  - "capture viewport"
+  - "export pdf"
+  - "canvas inspection"
+  - "extract design tokens"
+tools:
+  - "browser_screenshot"
+  - "browser_viewport"
+  - "browser_canvas"
+  - "browser_pdf"
+  - "browser_extract_design"
+  - "browser_map"
+  - "browser_click"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# Visual Capture, Canvas Forensics & Design Extraction
+
+Beyond textual DOM manipulation, modern web applications contain dynamic HTML5 canvas renderings (charts, maps, WebGL games), and agents often need high-fidelity visual artifacts.
+
+---
+
+## 1. Targeted Screenshots (`browser_screenshot`)
+
+Capture full page layouts, the visible viewport, or specific element bounding boxes:
+
+```json
+{
+  "fullPage": true,
+  "format": "png"
+}
+```
+
+Or target a specific element ref:
+```json
+{
+  "ref": "w:55",
+  "format": "jpeg",
+  "quality": 80
+}
+```
+
+---
+
+## 2. PDF Document Generation (`browser_pdf`)
+
+Render the current page into a print-ready PDF document with print CSS styles applied:
+
+```json
+{
+  "landscape": false,
+  "printBackground": true,
+  "paperWidth": 8.5,
+  "paperHeight": 11
+}
+```
+
+---
+
+## 3. HTML5 Canvas Pixel Inspection & Visual Grounding (`browser_canvas` & `browser_map`)
+
+When a chart or graphic is rendered via `<canvas>`, standard DOM reading tools cannot see individual buttons or nodes. You have two strategies:
+
+### A. Set-of-Marks Visual Grounding (Recommended for Canvas UIs & WebGL)
+Run `browser_map({ visual: "auto" })`. It detects canvas elements and high-contrast regions, attaches numbered badges `[1]…[N]`, and returns an annotated image:
+```json
+{
+  "visual": "auto"
+}
+```
+Then interact directly by mark number without guessing pixel coordinates:
+```json
+{
+  "mark": 3
+}
+```
+
+### B. Direct Canvas Pixel Export (`browser_canvas`)
+To extract the raw image data or draw programmatic gesture paths:
+```json
+{
+  "ref": "w:19",
+  "action": "toDataURL"
+}
+```
+
+---
+
+## 4. Design System Extraction (`browser_extract_design`)
+
+Reverse-engineer UI stylesheets, active CSS custom properties (variables), typography scales, and color palettes:
+
+```json
+{
+  "selector": ".antigravity-hud-panel"
+}
+```
+
+Returns structured JSON representing colors, font families, shadows, and spacing tokens.

package/documents/office-document-ingestion.md

@@ -0,0 +1,63 @@
+---
+id: office-document-ingestion
+domain: documents
+triggers:
+  - "read excel"
+  - "read docx"
+  - "parse csv"
+  - "spreadsheet"
+  - "word document"
+  - "parse table"
+tools:
+  - "browser_office"
+weavetab: ">=2.5.0-beta.5"
+---
+
+# Office Document Ingestion: Word, Excel & CSV Parsing
+
+Agents frequently need to parse structured spreadsheets or corporate documents downloaded during automation runs. `browser_office` parses `.docx`, `.xlsx`, `.xls`, and `.csv` files directly into clean JSON structures.
+
+---
+
+## 1. Parsing Spreadsheets (`.xlsx`, `.csv`)
+
+Stream structured sheet data, headers, and cell values:
+
+```json
+{
+  "filePath": "C:/Users/fy2ne/Downloads/quarterly_revenue.xlsx",
+  "sheet": "Q3_Summary",
+  "headerRow": 1,
+  "maxRows": 100
+}
+```
+
+### Response Example:
+```json
+{
+  "fileType": "xlsx",
+  "sheets": ["Q1", "Q2", "Q3_Summary"],
+  "rowCount": 45,
+  "data": [
+    { "Department": "Engineering", "Budget": 1250000, "Actual": 1180000 },
+    { "Department": "Marketing", "Budget": 600000, "Actual": 620000 }
+  ]
+}
+```
+
+---
+
+## 2. Ingesting Word Documents (`.docx`)
+
+Extract semantic paragraphs, document headings, tables, and lists:
+
+```json
+{
+  "filePath": "C:/Users/fy2ne/Documents/service_agreement.docx",
+  "extractTables": true
+}
+```
+
+### Operational Advantages:
+- Eliminates the need for heavy external Python libraries or microservices.
+- Safely sanitizes binary formats before passing content into LLM context.

package/evals/evaluator.js

@@ -0,0 +1,146 @@
+const fs = require('fs');
+const path = require('path');
+
+const packageRoot = path.join(__dirname, '..');
+const scenariosPath = path.join(packageRoot, 'evals', 'scenarios.json');
+const skillsJsonPath = path.join(packageRoot, 'skills.json');
+
+const OFFICIAL_TOOLS = new Set([
+  "browser_map", "browser_navigate", "browser_click", "browser_type",
+  "browser_type_secret", "browser_key", "browser_scroll", "browser_dialog",
+  "browser_burst", "browser_tabs", "browser_wait", "browser_captcha",
+  "browser_thoughts", "browser_pointer", "browser_select", "browser_fill",
+  "browser_highlight", "browser_upload", "browser_find", "browser_storage",
+  "browser_network_intercept", "browser_console", "browser_pdf", "browser_eval",
+  "browser_cookies", "browser_canvas", "browser_scrape", "browser_snapshot",
+  "browser_screenshot", "browser_viewport", "browser_clipboard", "browser_inspect",
+  "browser_extract_design", "browser_automation", "browser_recording",
+  "browser_detect", "browser_performance",
+  "browser_github", "browser_office", "browser_emulate",
+  "browser_checkpoint", "browser_pattern_learn"
+]);
+
+const BANNED_TOOLS = [
+  "browser_evaluate", "browser_ask", "scrape_page", "click_element", "fill_field"
+];
+
+console.log("====================================================");
+console.log("Weavetab Agent Skills Evaluation Harness (evals/)");
+console.log("====================================================");
+
+if (!fs.existsSync(scenariosPath)) {
+  console.error("Missing evals/scenarios.json");
+  process.exit(1);
+}
+
+if (!fs.existsSync(skillsJsonPath)) {
+  console.error("Missing skills.json. Run 'npm run build' first.");
+  process.exit(1);
+}
+
+const scenariosData = JSON.parse(fs.readFileSync(scenariosPath, 'utf8'));
+const skillsData = JSON.parse(fs.readFileSync(skillsJsonPath, 'utf8'));
+
+let passed = 0;
+let failed = 0;
+const errors = [];
+
+console.log(`Running evaluation on ${scenariosData.scenarios.length} scenarios...\n`);
+
+for (const scenario of scenariosData.scenarios) {
+  process.stdout.write(`  [TEST] ${scenario.id.padEnd(35)} `);
+
+  const guidePath = path.join(packageRoot, scenario.expectedDomain, scenario.expectedGuide);
+  if (!fs.existsSync(guidePath)) {
+    console.log("❌ FAIL: Guide file missing");
+    errors.push(`Scenario '${scenario.id}': Expected guide not found at ${guidePath}`);
+    failed++;
+    continue;
+  }
+
+  const guideContent = fs.readFileSync(guidePath, 'utf8');
+
+  // 1. Verify expected tools are documented
+  let toolsMissing = [];
+  for (const tool of scenario.expectedTools) {
+    if (!guideContent.includes(tool)) {
+      toolsMissing.push(tool);
+    }
+  }
+
+  if (toolsMissing.length > 0) {
+    console.log(`❌ FAIL: Missing tools (${toolsMissing.join(', ')})`);
+    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} does not document required tools: ${toolsMissing.join(', ')}`);
+    failed++;
+    continue;
+  }
+
+  // 2. Verify no banned tools in guide
+  let bannedFound = [];
+  for (const banned of scenario.bannedTools || BANNED_TOOLS) {
+    if (guideContent.includes(`\`${banned}\``) || guideContent.includes(`"${banned}"`)) {
+      bannedFound.push(banned);
+    }
+  }
+
+  if (bannedFound.length > 0) {
+    console.log(`❌ FAIL: Contains banned tools (${bannedFound.join(', ')})`);
+    errors.push(`Scenario '${scenario.id}': Guide ${scenario.expectedGuide} references banned tools: ${bannedFound.join(', ')}`);
+    failed++;
+    continue;
+  }
+
+  console.log("✔ PASS");
+  passed++;
+}
+
+// Global Check: Verify all 48 tools appear across the entire skill base
+console.log("\n----------------------------------------------------");
+console.log("Auditing Global Tool Coverage Across All 9 Domains...");
+const coveredTools = new Set();
+for (const skill of skillsData.skills) {
+  for (const t of skill.tools) {
+    coveredTools.add(t);
+  }
+}
+
+// Also scan markdown files for tools covered in text
+for (const domain of skillsData.domains) {
+  const dPath = path.join(packageRoot, domain);
+  if (!fs.existsSync(dPath)) continue;
+  for (const f of fs.readdirSync(dPath).filter(x => x.endsWith('.md'))) {
+    const content = fs.readFileSync(path.join(dPath, f), 'utf8');
+    for (const tool of OFFICIAL_TOOLS) {
+      if (content.includes(tool)) {
+        coveredTools.add(tool);
+      }
+    }
+  }
+}
+
+let uncoveredTools = [];
+for (const tool of OFFICIAL_TOOLS) {
+  if (!coveredTools.has(tool)) {
+    uncoveredTools.push(tool);
+  }
+}
+
+console.log(`Official Tools In MCP: ${OFFICIAL_TOOLS.size}`);
+console.log(`Covered in Skills:     ${coveredTools.size}`);
+
+if (uncoveredTools.length > 0) {
+  console.warn(`⚠️ Warning: Uncovered tools in skills: ${uncoveredTools.join(', ')}`);
+}
+
+console.log("====================================================");
+console.log(`Test Summary: ${passed} Passed, ${failed} Failed`);
+console.log("====================================================");
+
+if (failed > 0) {
+  console.error("\nFailure details:");
+  errors.forEach(err => console.error(`  - ${err}`));
+  process.exit(1);
+} else {
+  console.log("\nAll benchmark evaluation tests passed successfully.");
+  process.exit(0);
+}