@weavetab/mcp 2.5.0-beta.4 → 2.5.0

package/README.md

@@ -1,17 +1,15 @@
 <div align="center">
 
-<img src="icon.png" width="96" alt="Weavetab" /><br /><br />
+<img src="weavetab-banner.png"  alt="Weavetab" /><br /><br />
 
-<h1>Weavetab MCP</h1>
-
-<p>A local <a href="https://modelcontextprotocol.io">Model Context Protocol</a> server that gives AI agents<br />direct, physical control over browsers and desktop applications via the Chrome DevTools Protocol.</p>
+<p>The open automation engine for AI agents.<br />Control live browsers and desktop apps locally with instant execution.</p>
 
 <p>
   <a href="https://github.com/weavetab/mcp/releases"><img src="https://img.shields.io/github/v/release/weavetab/mcp?label=version&style=flat-square&color=3b82f6" alt="version" /></a>
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-AGPL--3.0-8b5cf6?style=flat-square" alt="license" /></a>
   <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-10b981?style=flat-square" alt="MCP" /></a>
   <img src="https://img.shields.io/badge/Node.js-%3E%3D18-green?style=flat-square" alt="Node" />
-  <a href="docs/tools/tools.md"><img src="https://img.shields.io/badge/tools-44-ec4899?style=flat-square" alt="tools" /></a>
+  <a href="docs/tools/tools.md"><img src="https://img.shields.io/badge/tools-42-ec4899?style=flat-square" alt="tools" /></a>
   <a href="https://github.com/sponsors/fy2ne"><img src="https://img.shields.io/badge/sponsor-fy2ne-ea4aaa?style=flat-square&logo=github-sponsors" alt="sponsor" /></a>
 </p>
 
@@ -27,27 +25,27 @@
 
 ---
 
-Weavetab is a local, production-grade MCP server that connects AI agents directly to Chromium browsers and Electron desktop applications through the **Chrome DevTools Protocol (CDP) WebSocket at Layer 0** — no WebDriver binaries, no Playwright processes, no cloud relay.
+Weavetab is the open automation engine for AI agents. It connects models directly to live Chromium browsers and Electron desktop applications via native **Chrome DevTools Protocol (CDP)** sockets — no WebDriver binaries, no cloud relay, zero telemetry.
 
-Tool invocations resolve in **3–8 ms of mean latency**. DOM state is compressed into agent-readable semantic maps and diffed across turns, cutting prompt token usage by **up to 95%**. Security is enforced locally via per-domain policies, 4-tier RBAC, and cryptographic blind credential injection.
+Actions execute with **sub-10ms latency**. Web pages are translated into agent-readable semantic maps with turn-by-turn diffing that reduces token usage by **up to 95%**. Built-in security enforces local domain policies, role-based access control, and client-side credential injection.
 
-Built by [fy2ne](https://github.com/fy2ne).
+Built and architected by [fy2ne](https://github.com/fy2ne).
 
 ---
 
 ## Why not Playwright or Puppeteer?
 
-> The standard approach — Playwright over MCP — works. But it carries fundamental architectural costs that compound at scale.
+> The standard approach ΓÇö Playwright over MCP ΓÇö works. But it carries fundamental architectural costs that compound at scale.
 
 |  | Playwright / Puppeteer | **Weavetab** |
 |---|---|---|
 | **Protocol layer** | WebDriver BiDi or CDP via browser binary | Raw CDP WebSocket, Layer 0 |
-| **Tool execution latency** | 50–300 ms (binary + IPC overhead) | **3–8 ms** |
-| **Desktop app control** | Browser only | Chrome + any Electron app (Discord, VS Code, Figma…) |
+| **Tool execution latency** | 50ΓÇô300 ms (binary + IPC overhead) | **3ΓÇô8 ms** |
+| **Desktop app control** | Browser only | Chrome + any Electron app (Discord, VS Code, Figma…) |
 | **DOM representation** | Full HTML dump to LLM | Semantic Map 3.0 with delta diffing |
-| **Token cost per map** | ~2,000–8,000 tokens | **~80–400 tokens** (95% reduction via delta) |
+| **Token cost per map** | ~2,000ΓÇô8,000 tokens | **~80ΓÇô400 tokens** (95% reduction via delta) |
 | **CAPTCHA** | API service required | **Zero-API** via CDP mouse physics |
-| **Credential safety** | Secrets passed in plaintext | **Blind Injection** — never in LLM context |
+| **Credential safety** | Secrets passed in plaintext | **Blind Injection** ΓÇö never in LLM context |
 | **Extension access** | Limited | Full Chrome Extension API surface |
 
 ---
@@ -64,14 +62,14 @@ MCP Client (Claude / Cursor / Antigravity / Copilot / Windsurf)
 |                                                             |
 |  +-----------------+   +---------------------------------+  |
 |  | Security Layer  |-->|  Intelligence Engine            |  |
-|  | Rate · RBAC     |   |  Map 3.0 · Delta · Memory       |  |
-|  | Policy · Audit  |   |  Pruner · Framework Detector    |  |
+|  | Rate ┬╖ RBAC     |   |  Map 3.0 ┬╖ Delta ┬╖ Memory       |  |
+|  | Policy ┬╖ Audit  |   |  Pruner ┬╖ Framework Detector    |  |
 |  +-----------------+   +----------------+----------------+  |
 |                                         |                   |
 |                              +----------v----------------+  |
 |                              |  CDP Bridge               |  |
-|                              |  Ghost Cursor · Typing    |  |
-|                              |  App Router · Loop Guard  |  |
+|                              |  Ghost Cursor ┬╖ Typing    |  |
+|                              |  App Router ┬╖ Loop Guard  |  |
 |                              +----------+----------------+  |
 +-------------------------------------------------------------+
                                           |  CDP WebSocket (127.0.0.1)
@@ -122,10 +120,10 @@ Add to your MCP client config:
 The primary bottleneck in browser-based agents is DOM representation. Full HTML dumps are noisy, large, and structurally meaningless to language models. Weavetab's `browser_map` runs an in-browser CDP walker that produces a compact semantic map:
 
 ```
-╔═ ACTIVE DIALOG: "Confirm Payment" ═╗
+ΓòöΓòÉ ACTIVE DIALOG: "Confirm Payment" ΓòÉΓòù
   [w:3] button "Confirm"  [w:4] button "Cancel"
 
-┌ "Pro Plan — $49/mo"
+Γöî "Pro Plan ΓÇö $49/mo"
   [w:12] button "Upgrade"   [w:13] button "View Details"
   [w:14] input val:"john@example.com"  ph:"Email address"  FOCUSED
 
@@ -135,10 +133,10 @@ The primary bottleneck in browser-based agents is DOM representation. Full HTML
 Key properties:
 
 - **Ref IDs** (`w:N`) are stable within a session and used by all interaction tools
-- **Container binding** — buttons and inputs are grouped under their parent card, row, or section header
-- **Modal hoisting** — open dialogs are isolated at the top so agents cannot miss them
-- **Link collapsing** — repeated nav/footer runs of 4+ links compress into a single token line
-- **Semantic delta** — on re-reads, only changed nodes are transmitted (`~` modified, `+` added, `−` removed), cutting re-read cost by up to 95%
+- **Container binding** ΓÇö buttons and inputs are grouped under their parent card, row, or section header
+- **Modal hoisting** ΓÇö open dialogs are isolated at the top so agents cannot miss them
+- **Link collapsing** ΓÇö repeated nav/footer runs of 4+ links compress into a single token line
+- **Semantic delta** — on re-reads, only changed nodes are transmitted (`~` modified, `+` added, `−` removed), cutting re-read cost by up to 95%
 
 ### Ghost Cursor
 
@@ -186,13 +184,13 @@ Weavetab auto-attaches via CDP to the registered process. No code changes requir
 
 ### Zero-API CAPTCHA Solving
 
-`browser_captcha` solves Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha by orchestrating CDP mouse events that replicate human behavioral signatures — velocity curves, micro-pauses, scroll inertia — with no third-party API, no external service, and no API key required.
+`browser_captcha` solves Cloudflare Turnstile, reCAPTCHA v2/v3, GeeTest, and hCaptcha by orchestrating CDP mouse events that replicate human behavioral signatures ΓÇö velocity curves, micro-pauses, scroll inertia ΓÇö with no third-party API, no external service, and no API key required.
 
 ---
 
 ## Tool Suite
 
-44 tools across 9 categories. Full parameter reference: [`docs/tools/tools.md`](docs/tools/tools.md)
+42 tools across 9 categories. Full parameter reference: [`docs/tools/tools.md`](docs/tools/tools.md)
 
 | Category | Tools |
 |---|---|
@@ -204,7 +202,7 @@ Weavetab auto-attaches via CDP to the registered process. No code changes requir
 | **Autonomous CAPTCHA** | `browser_captcha` |
 | **Network & Storage** | `browser_network_intercept` `browser_storage` `browser_cookies` `browser_checkpoint` `browser_performance` |
 | **GitHub & Documents** | `browser_github` `browser_office` |
-| **Canvas, Eval & Plugins** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` `list_plugins` `load_plugin` |
+| **Canvas & Eval** | `browser_eval` `browser_pdf` `browser_canvas` `browser_highlight` |
 
 ---
 
@@ -212,7 +210,7 @@ Weavetab auto-attaches via CDP to the registered process. No code changes requir
 
 - **Transport**: CDP WebSocket strictly bound to `127.0.0.1`. No listener on external interfaces.
 - **Policy Engine**: Per-domain `allow` / `read-only` / `deny` / `audit` rules in `~/.weavetab/policy.json`
-- **RBAC**: Four roles — `admin`, `operator`, `viewer`, `automation` — enforce tool-level permission gates
+- **RBAC**: Four roles ΓÇö `admin`, `operator`, `viewer`, `automation` ΓÇö enforce tool-level permission gates
 - **Blind Injection**: Credentials resolved server-side, masked in all outputs and audit logs
 - **Loop Breaker**: Strike-based stuck-loop detector halts runaway autonomous sequences
 - **Audit Log**: All tool invocations, policy decisions, and errors written to `~/.weavetab/logs/audit.log`

package/dist/cdp/connector.js

@@ -614,7 +614,7 @@ export async function getTabList(agentId, targetApp) {
         }
     }
     if (!port)
-        throw new Error(`[!] No active ${targetApp ? targetApp : "browser"} session. Run browser_go or launch app first.`);
+        throw new Error(`[!] No active ${targetApp ? targetApp : "browser"} session. Run browser_navigate or launch app first.`);
     try {
         const metaSession = await withCDPTimeout(CDP({ host: "127.0.0.1", port }), 5000, "getTabList CDP");
         const { targetInfos } = await withCDPTimeout(metaSession.Target.getTargets(), 5000, "getTabList getTargets");
@@ -671,7 +671,7 @@ export async function connectToTab(targetId, port, agentId, browserContextId, ap
     const lock = readLock(appName);
     const p = port || (appName ? lock?.port : (actualPort || lock?.port));
     if (!p)
-        throw new Error(`[!] No active ${appName || "browser"} session. Run browser_go first.`);
+        throw new Error(`[!] No active ${appName || "browser"} session. Run browser_navigate first.`);
     let t = null;
     try {
         const targets = await withCDPTimeout(CDP.List({ host: "127.0.0.1", port: p }), 3000, "connectToTab CDP.List");

package/dist/cli/plugin.d.ts

@@ -1,4 +1,5 @@
 export declare function runPluginAdd(inputName: string, args?: string[]): Promise<void>;
+export declare function runPluginAddLocal(inputPath: string): Promise<void>;
 export declare function runPluginList(): Promise<void>;
 export declare function runPluginSearch(query?: string): Promise<void>;
 export declare function runPluginBrowse(): Promise<void>;

package/dist/cli/plugin.js

@@ -2,6 +2,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 import boxen from "boxen";
 import ora from "ora";
+import fs from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
 import { createRequire } from "node:module";
@@ -24,7 +25,7 @@ function runCommand(cmd, cmdArgs, cwd = process.cwd()) {
         const executable = isWin && !cmd.endsWith(".cmd") && !cmd.endsWith(".exe") ? `${cmd}.cmd` : cmd;
         const child = spawn(executable, cmdArgs, {
             cwd,
-            shell: false,
+            shell: isWin,
             stdio: ["ignore", "pipe", "pipe"],
         });
         let stdout = "";
@@ -47,8 +48,20 @@ function runNpmCommand(cmdArgs, cwd = process.cwd()) {
 // ---------------------------------------------------------------------------
 export async function runPluginAdd(inputName, args = []) {
     if (!inputName || inputName.startsWith("-")) {
-        console.log(pc.red("[ERROR] Please provide a package name to install."));
-        console.log(pc.dim("Usage: weavetab plugin add <packageName> [--official | --community] [--yes]"));
+        console.log(pc.red("[ERROR] Please provide a package name or local path to install."));
+        console.log(pc.dim("Usage: weavetab plugin add <packageName|./local-path> [--official | --community] [--yes]"));
+        return;
+    }
+    // Local path install: `weavetab plugin add ./my-plugin` (npm installs the directory).
+    if (inputName === "." ||
+        inputName.startsWith("./") ||
+        inputName.startsWith("../") ||
+        inputName.startsWith("file:") ||
+        inputName.startsWith("/") ||
+        inputName.startsWith("\\") ||
+        /^[a-zA-Z]:[\\/]/.test(inputName) ||
+        inputName.startsWith("~/")) {
+        await runPluginAddLocal(inputName);
         return;
     }
     const isForce = args.includes("--yes") || args.includes("-y") || args.includes("--force");
@@ -223,6 +236,49 @@ export async function runPluginAdd(inputName, args = []) {
     }
 }
 // ---------------------------------------------------------------------------
+// 1b. ADD FROM LOCAL PATH (`weavetab plugin add ./my-plugin`)
+// ---------------------------------------------------------------------------
+export async function runPluginAddLocal(inputPath) {
+    let dir = inputPath;
+    if (dir.startsWith("file:"))
+        dir = dir.slice("file:".length);
+    if (dir.startsWith("~/"))
+        dir = path.join(process.env.HOME || process.env.USERPROFILE || "", dir.slice(2));
+    const absDir = path.resolve(process.cwd(), dir);
+    if (!fs.existsSync(absDir) || !fs.statSync(absDir).isDirectory()) {
+        console.log(pc.red(`[ERROR] Local path not found: ${inputPath}`));
+        return;
+    }
+    const local = inspectInstalledPackage(absDir);
+    if (!local) {
+        console.log(pc.red(`[ERROR] No valid weavetab.json manifest in ${absDir}`));
+        console.log(pc.dim("Scaffold one with: npx @weavetab/sdk init <name>"));
+        return;
+    }
+    const spinner = ora(`Installing local plugin ${pc.cyan(local.packageName)} from ${pc.dim(absDir)} via npm...`).start();
+    const installResult = await runNpmCommand(["install", absDir]);
+    if (installResult.code !== 0) {
+        spinner.fail(pc.red(`Failed to install ${local.packageName}`));
+        if (installResult.stderr)
+            console.error(pc.dim(installResult.stderr));
+        return;
+    }
+    spinner.succeed(pc.green(`installed ${pc.bold(local.packageName)} (local path)`));
+    const targetDir = path.join(process.cwd(), "node_modules", local.packageName);
+    const installedInfo = fs.existsSync(targetDir) ? inspectInstalledPackage(targetDir) : local;
+    const manifest = (installedInfo?.manifest || local.manifest);
+    const tools = manifest.tools || [];
+    console.log();
+    console.log(boxen(`${pc.bold("Plugin Details:")}\n` +
+        `  ${pc.dim("Name:")}        ${manifest.name || local.packageName}\n` +
+        `  ${pc.dim("Version:")}     ${manifest.version || "1.0.0"}\n` +
+        `  ${pc.dim("Source:")}      ${absDir} (local path)\n` +
+        `  ${pc.dim("Description:")} ${manifest.description || "No description provided"}` +
+        (tools.length > 0 ? `\n\n${pc.bold(`Exposed Tools (${tools.length}):`)}` + tools.map((t) => `\n  • ${pc.cyan(t.name)}: ${pc.dim(t.description || "")}`).join("") : ""), { padding: 1, borderStyle: "round", borderColor: "green" }));
+    console.log();
+    console.log(pc.green("✔ Plugin is ready to use! Restart Weavetab MCP server to activate changes.\n"));
+}
+// ---------------------------------------------------------------------------
 // 2. LIST INSTALLED PLUGINS
 // ---------------------------------------------------------------------------
 export async function runPluginList() {
@@ -434,7 +490,7 @@ export async function runPluginCli(args) {
         console.log(`  weavetab plugin <command> [options]`);
         console.log();
         console.log(pc.bold("COMMANDS"));
-        console.log(`  ${pc.cyan("add <pkg>")}          Install any plugin by npm package name (e.g. @fy2ne/wt-youtube, my-plugin)`);
+        console.log(`  ${pc.cyan("add <pkg|path>")}     Install a plugin by npm name or local path (e.g. @fy2ne/wt-youtube, ./my-plugin)`);
         console.log(`  ${pc.cyan("browse")}             Interactive terminal explorer to browse & 1-click install`);
         console.log(`  ${pc.cyan("search [query]")}     Search plugins across official registry & npm`);
         console.log(`  ${pc.cyan("list")}               List all installed plugins and their registered tools`);

package/dist/config/loader.d.ts

@@ -1,6 +1,6 @@
 export type DevModeConfig = boolean;
 export type PolicyMode = "allow" | "deny" | "audit-only" | "read-only";
-export type Role = "admin" | "viewer" | "automation" | "system";
+export type Role = "admin" | "operator" | "viewer" | "automation" | "system";
 export type BrowserEngine = "chromium" | "firefox" | "webkit";
 export interface PolicyEntry {
     pattern: string;

package/dist/config/loader.js

@@ -153,7 +153,7 @@ export function validateConfigInternal(raw) {
     const d = DEFAULT_CONFIG;
     const VALID_MODES = ["session", "attach"];
     const VALID_ENGINES = ["chromium", "firefox", "webkit"];
-    const VALID_ROLES = ["admin", "viewer", "automation", "system"];
+    const VALID_ROLES = ["admin", "operator", "viewer", "automation", "system"];
     const mode = validateField("mode", raw.mode, isStr, d.mode, v => VALID_MODES.includes(v));
     // Path validation helpers
     function safePathField(field, value) {

package/dist/index.js

@@ -98,6 +98,32 @@ function printBootBanner(port) {
 async function main() {
     assertNotRoot();
     const args = process.argv.slice(2);
+    // Global flags: --version always works; --ws starts the WebSocket daemon.
+    if (args.includes("--version") || args.includes("-v")) {
+        const _v = createRequire(import.meta.url);
+        const ver = _v("../package.json").version || WEAVETAB_VERSION;
+        console.log(`@weavetab/mcp v${ver}`);
+        process.exit(0);
+    }
+    if (args.includes("--ws")) {
+        let wsPort = 3000;
+        const pi = args.findIndex((a) => a === "--port");
+        const eq = args.find((a) => a.startsWith("--port="));
+        const rawPort = pi >= 0 ? args[pi + 1] : eq ? eq.slice("--port=".length) : undefined;
+        if (rawPort !== undefined) {
+            const parsed = parseInt(rawPort, 10);
+            if (isNaN(parsed) || parsed < 1 || parsed > 65535) {
+                console.error(`[Weavetab] Invalid --port value: "${rawPort}" (1-65535).`);
+                process.exit(1);
+            }
+            wsPort = parsed;
+        }
+        const config = await loadConfig();
+        global.__wt_is_server = true;
+        await printBootBanner(wsPort);
+        await startServer(config, "ws", wsPort);
+        return;
+    }
     // If NOT in a TTY environment (e.g. spawned by Claude Code as MCP server)
     if (!isInteractive && args.length === 0) {
         // Singleton guard — exit immediately if another MCP server is alive.
@@ -363,6 +389,7 @@ async function main() {
             S.sl("Role *", {
                 initialValue: "admin", options: [
                     { value: "admin", label: "Admin", hint: "Full access to all tools" },
+                    { value: "operator", label: "Operator", hint: "Full access, standard agent role" },
                     { value: "viewer", label: "Viewer", hint: "Read-only access (map, find, scrape, console)" },
                     { value: "automation", label: "Automation", hint: "CI/CD mode (burst, plan, wait, map)" },
                 ]
@@ -702,7 +729,7 @@ async function main() {
                 summary.push(`${pc.dim("Allowed:")}   ${a.allow.join(", ")}`);
             p.note(summary.join("\n"), "SUMMARY");
             if (!mcpConfigured) {
-                console.log(pc.dim("\nTo configure MCP manually, run: weavetab config-mcp"));
+                console.log(pc.dim("\nTo configure MCP manually, run: weavetab config"));
             }
             p.outro(`${pc.green("Weavetab is ready!")}  ${pc.dim("Run")} ${pc.cyan("weavetab help")} ${pc.dim("to see available commands.")}`);
         }
@@ -1165,8 +1192,10 @@ async function main() {
         console.log(`  ${pc.cyan("skills")}        Install or update AI agent skills (@weavetab/skills)`);
         console.log(`  ${pc.cyan("view")}          Display the current active configuration`);
         console.log(`  ${pc.cyan("reset")}         Purge browser profiles, lockfiles, and orphan processes`);
-        console.log(`  ${pc.cyan("secrets")}       Manage blind-injected credentials (set, list, rm)`);
+        console.log(`  ${pc.cyan("secrets")}       Manage blind-injected credentials (set, list, rm, init)`);
         console.log(`  ${pc.cyan("reload-ext")}    Send a reload signal to the browser extension`);
+        console.log(`  ${pc.cyan("--ws")}          Start the WebSocket daemon (default port 3000, override with --port)`);
+        console.log(`  ${pc.cyan("--version")}     Print version and exit`);
         console.log(`  ${pc.cyan("help")}          Show this help message`);
         console.log();
         console.log(pc.bold("AGENT SKILLS (@weavetab/skills)"));
@@ -1174,7 +1203,7 @@ async function main() {
         console.log(`  ${pc.dim("Via CLI:")}               ${pc.cyan("weavetab skills [options]")}`);
         console.log();
         console.log(pc.bold("PLUGIN COMMANDS (User)"));
-        console.log(`  ${pc.cyan("weavetab plugin add <pkg>")}         Install a plugin (resolves official @weavetab/plugin- & community)`);
+        console.log(`  ${pc.cyan("weavetab plugin add <pkg>")}         Install a plugin from npm (or a local path: ./my-plugin)`);
         console.log(`  ${pc.cyan("weavetab plugin browse")}            Interactive terminal explorer to browse & 1-click install`);
         console.log(`  ${pc.cyan("weavetab plugin search <query>")}    Search plugins across registry & npm`);
         console.log(`  ${pc.cyan("weavetab plugin list")}              List all installed Weavetab plugins and tools`);
@@ -1198,7 +1227,7 @@ async function main() {
         console.log(pc.bold("LINKS"));
         console.log(`  ${pc.cyan("GitHub:")}  ${pc.dim("https://github.com/weavetab")}`);
         console.log(`  ${pc.cyan("npm:")}     ${pc.dim("https://www.npmjs.com/package/@weavetab/mcp")}`);
-        console.log(`  ${pc.cyan("Website:")} ${pc.dim("https://github.com/weavetab/mcp")}`);
+        console.log(`  ${pc.cyan("Website:")} ${pc.dim("https://weavetab.dev")}`);
         console.log();
     }
 }
@@ -1237,10 +1266,17 @@ async function runSecretsCommand(args) {
     const { secretStore } = await import("./security/secrets.js");
     const p = await import("@clack/prompts");
     if (args.length === 0) {
-        console.log(pc.red("[ERROR] Usage: weavetab secrets <set|list|rm> [key]"));
+        console.log(pc.red("[ERROR] Usage: weavetab secrets <set|list|rm|init> [key]"));
         process.exit(1);
     }
     const subcmd = args[0].toLowerCase();
+    if (subcmd === "init") {
+        const { initProjectSecrets } = await import("./security/secrets.js");
+        const filePath = initProjectSecrets();
+        console.log(pc.green(`[OK] Project secrets initialized: ${filePath}`));
+        console.log(pc.dim("Keys in this file take precedence over ~/.weavetab/secrets.json when Weavetab runs from this directory."));
+        return;
+    }
     if (subcmd === "list") {
         const list = await secretStore.listSecrets();
         console.log(boxen(pc.cyan("STORED SECRETS"), { padding: 1, borderStyle: 'round', borderColor: 'cyan' }));
@@ -1319,6 +1355,6 @@ async function runSecretsCommand(args) {
         return;
     }
     console.log(pc.red(`[ERROR] Unknown secrets command: ${subcmd}`));
-    console.log(pc.red("Usage: weavetab secrets <set|list|rm> [key]"));
+    console.log(pc.red("Usage: weavetab secrets <set|list|rm|init> [key]"));
     process.exit(1);
 }

package/dist/plugin/interface.d.ts

@@ -57,6 +57,7 @@ export interface WeavetabPermissions {
         reason?: string;
         [key: string]: any;
     };
+    /** @deprecated use `filesystem` */
     fs?: {
         read?: string[];
         write?: string[];
@@ -68,11 +69,19 @@ export interface WeavetabPermissions {
         reason?: string;
     };
     tools?: {
-        /** List of built-in tool names this plugin is permitted to override */
+        /** Must be true for the plugin to register any new MCP tools */
+        add?: boolean;
+        /** Explicit list of built-in tool names this plugin may override */
         override?: string[];
-        /** List of built-in tool names this plugin is permitted to remove */
+        /** Explicit list of built-in tool names this plugin may remove */
         remove?: string[];
-        hooks?: boolean;
+        reason?: string;
+    };
+    hooks?: {
+        onBeforeAction?: boolean;
+        onAfterAction?: boolean;
+        onDOMMutation?: boolean;
+        onPageNavigate?: boolean;
         reason?: string;
     };
     [key: string]: any;
@@ -121,8 +130,6 @@ export interface WeavetabManifest {
     engines?: Record<string, string>;
     /** Supported environments */
     environments?: string[];
-    /** Whether the plugin should be lazy-loaded on demand */
-    lazy?: boolean;
     /** Tools exposed by this plugin to the MCP server */
     tools?: WeavetabManifestTool[];
     /** Default configuration template */
@@ -236,6 +243,7 @@ export interface WeavetabPluginDefinition {
     overrides?: WeavetabToolOverride[];
     removeTools?: string[];
     defaultConfig?: Record<string, any>;
+    permissions?: WeavetabPermissions;
     onBeforeAction?: BeforeActionHook;
     onAfterAction?: AfterActionHook;
     onDOMMutation?: DOMMutationHook;
@@ -246,6 +254,7 @@ export interface WeavetabPlugin {
     name: string;
     version: string;
     description?: string;
+    permissions?: WeavetabPermissions;
     /** Add new tools */
     tools?: WeavetabToolDefinition[] | WeavetabPluginTool[];
     /** Override or wrap existing tools */

package/dist/plugin/loader.d.ts

@@ -21,9 +21,6 @@ export declare function inspectInstalledPackage(pkgDir: string): InstalledPlugin
  * Scan node_modules and return metadata for all installed Weavetab plugins.
  */
 export declare function listInstalledPlugins(pluginDir?: string): InstalledPluginInfo[];
-/**
- * Builds the canonical rich PluginContext for a loaded plugin.
- */
 export declare function buildPluginContext(plugin: WeavetabPlugin, storageManager: PluginStorageManager, extensionBridge: PluginExtensionBridge, pluginConfig: Record<string, any>, hooks: {
     beforeToolCall: Array<(toolName: string, args: Record<string, any>, session?: any) => Promise<any> | void>;
     afterToolCall: Array<(toolName: string, args: Record<string, any>, result: any, session?: any) => Promise<any> | void>;

package/dist/plugin/loader.js

@@ -27,9 +27,9 @@ function getNodeModulesDirs(customDir) {
 export function normalizePermissions(perms) {
     if (!perms)
         return {};
-    // Handle flat string array: ["browser.evaluate", "browser.navigate", "fs.read", ...]
+    // Handle flat string array: ["browser.evaluate", "tools.add", "tools", "fs.read", ...]
     if (Array.isArray(perms)) {
-        const normalized = { cdp: {}, fs: {}, extension: {} };
+        const normalized = { cdp: {}, fs: {}, filesystem: {}, extension: {}, tools: {}, hooks: {} };
         for (const item of perms) {
             if (typeof item !== "string")
                 continue;
@@ -39,10 +39,27 @@ export function normalizePermissions(perms) {
             }
             else if (cat === "fs" || cat === "filesystem") {
                 normalized.fs[sub || "read"] = ["*"];
+                normalized.filesystem[sub || "read"] = ["*"];
             }
             else if (cat === "extension" || cat === "hud") {
                 normalized.extension[sub || "hud"] = true;
             }
+            else if (cat === "tools") {
+                normalized.tools = normalized.tools || {};
+                if (!sub || sub === "add") {
+                    normalized.tools.add = true;
+                }
+            }
+            else if (cat === "hooks") {
+                normalized.hooks = normalized.hooks || {};
+                if (sub) {
+                    normalized.hooks[sub] = true;
+                }
+                else {
+                    normalized.hooks.onBeforeAction = true;
+                    normalized.hooks.onAfterAction = true;
+                }
+            }
         }
         return normalized;
     }
@@ -165,12 +182,11 @@ export function listInstalledPlugins(pluginDir) {
     }
     return results;
 }
-/**
- * Builds the canonical rich PluginContext for a loaded plugin.
- */
 export function buildPluginContext(plugin, storageManager, extensionBridge, pluginConfig, hooks) {
+    const perms = plugin.manifest?.permissions ?? {};
+    const pname = plugin.name;
     return {
-        name: plugin.name,
+        name: pname,
         version: plugin.version,
         pluginDir: storageManager.getDirectory(),
         config: pluginConfig,
@@ -178,34 +194,61 @@ export function buildPluginContext(plugin, storageManager, extensionBridge, plug
         extension: extensionBridge,
         mcp: {
             registerTool: (tool) => {
+                if (!perms.tools?.add) {
+                    console.error(`[Plugin: ${pname}] blocked registerTool("${tool?.name}"): permissions.tools.add not declared`);
+                    return;
+                }
                 plugin.tools = plugin.tools || [];
-                const existingIndex = plugin.tools.findIndex((t) => t.name === tool.name);
-                if (existingIndex >= 0) {
-                    plugin.tools[existingIndex] = tool;
+                const idx = plugin.tools.findIndex((t) => t.name === tool.name);
+                if (idx >= 0) {
+                    plugin.tools[idx] = tool;
                 }
                 else {
                     plugin.tools.push(tool);
                 }
             },
             overrideTool: (toolName, overrideHandler) => {
+                const allowed = perms.tools?.override ?? [];
+                if (!allowed.includes(toolName)) {
+                    console.error(`[Plugin: ${pname}] blocked overrideTool("${toolName}"): not listed in permissions.tools.override`);
+                    return;
+                }
                 plugin.overrides = plugin.overrides || [];
                 plugin.overrides.push({ name: toolName, handler: overrideHandler });
             },
             removeTool: (toolName) => {
+                const allowed = perms.tools?.remove ?? [];
+                if (!allowed.includes(toolName)) {
+                    console.error(`[Plugin: ${pname}] blocked removeTool("${toolName}"): not listed in permissions.tools.remove`);
+                    return;
+                }
                 plugin.removeTools = plugin.removeTools || [];
                 plugin.removeTools.push(toolName);
             },
             unregisterTool: (toolName) => {
+                const allowed = perms.tools?.remove ?? [];
+                if (!allowed.includes(toolName)) {
+                    console.error(`[Plugin: ${pname}] blocked unregisterTool("${toolName}"): not listed in permissions.tools.remove`);
+                    return;
+                }
                 plugin.removeTools = plugin.removeTools || [];
                 plugin.removeTools.push(toolName);
             },
         },
         hooks: {
             onBeforeAction: (fn) => {
+                if (!perms.hooks?.onBeforeAction) {
+                    console.error(`[Plugin: ${pname}] blocked onBeforeAction hook: permissions.hooks.onBeforeAction not declared`);
+                    return;
+                }
                 if (typeof fn === "function")
                     hooks.beforeToolCall.push(fn);
             },
             onAfterAction: (fn) => {
+                if (!perms.hooks?.onAfterAction) {
+                    console.error(`[Plugin: ${pname}] blocked onAfterAction hook: permissions.hooks.onAfterAction not declared`);
+                    return;
+                }
                 if (typeof fn === "function") {
                     hooks.afterToolCall.push(async (toolName, args, result, session) => {
                         return await fn(toolName, result, session, args);
@@ -213,18 +256,34 @@ export function buildPluginContext(plugin, storageManager, extensionBridge, plug
                 }
             },
             onDOMMutation: (fn) => {
+                if (!perms.hooks?.onDOMMutation) {
+                    console.error(`[Plugin: ${pname}] blocked onDOMMutation hook: permissions.hooks.onDOMMutation not declared`);
+                    return;
+                }
                 if (typeof fn === "function")
                     hooks.onDOMMutation?.push(fn);
             },
             beforeToolCall: (fn) => {
+                if (!perms.hooks?.onBeforeAction) {
+                    console.error(`[Plugin: ${pname}] blocked beforeToolCall hook: permissions.hooks.onBeforeAction not declared`);
+                    return;
+                }
                 if (typeof fn === "function")
                     hooks.beforeToolCall.push(fn);
             },
             afterToolCall: (fn) => {
+                if (!perms.hooks?.onAfterAction) {
+                    console.error(`[Plugin: ${pname}] blocked afterToolCall hook: permissions.hooks.onAfterAction not declared`);
+                    return;
+                }
                 if (typeof fn === "function")
                     hooks.afterToolCall.push(fn);
             },
             onPageNavigate: (fn) => {
+                if (!perms.hooks?.onPageNavigate) {
+                    console.error(`[Plugin: ${pname}] blocked onPageNavigate hook: permissions.hooks.onPageNavigate not declared`);
+                    return;
+                }
                 if (typeof fn === "function")
                     hooks.onPageNavigate.push(fn);
             },
@@ -237,10 +296,10 @@ export function buildPluginContext(plugin, storageManager, extensionBridge, plug
             recordQuirk: (origin, quirkKey, quirkData) => recordQuirk(origin, quirkKey, quirkData),
         },
         logger: {
-            info: (...args) => console.error(`[Plugin: ${plugin.name}] [INFO]`, ...args),
-            warn: (...args) => console.error(`[Plugin: ${plugin.name}] [WARN]`, ...args),
-            error: (...args) => console.error(`[Plugin: ${plugin.name}] [ERROR]`, ...args),
-            debug: (...args) => console.error(`[Plugin: ${plugin.name}] [DEBUG]`, ...args),
+            info: (...args) => console.error(`[Plugin: ${pname}] [INFO]`, ...args),
+            warn: (...args) => console.error(`[Plugin: ${pname}] [WARN]`, ...args),
+            error: (...args) => console.error(`[Plugin: ${pname}] [ERROR]`, ...args),
+            debug: (...args) => console.error(`[Plugin: ${pname}] [DEBUG]`, ...args),
         },
     };
 }
@@ -288,7 +347,10 @@ function tryLoadPlugin(pkgDir) {
         }
         const pluginModule = require(resolvedEntry);
         const plugin = pluginModule.default || pluginModule.plugin || pluginModule;
-        const normalizedPerms = normalizePermissions(manifest.permissions);
+        const rawPerms = Array.isArray(manifest.permissions)
+            ? manifest.permissions
+            : { ...(plugin?.permissions || {}), ...(manifest?.permissions || {}) };
+        const normalizedPerms = normalizePermissions(rawPerms);
         if (plugin &&
             (Array.isArray(plugin.tools) ||
                 Array.isArray(plugin.overrides) ||
@@ -302,9 +364,10 @@ function tryLoadPlugin(pkgDir) {
             plugin.version = plugin.version || manifest.version || pkg.version || "1.0.0";
             plugin.description = plugin.description || manifest.description || pkg.description || "";
             plugin.manifest = manifest;
+            plugin.permissions = normalizedPerms;
+            plugin.manifest.permissions = normalizedPerms;
             plugin.tools = Array.isArray(plugin.tools) ? plugin.tools : [];
             plugin.overrides = Array.isArray(plugin.overrides) ? plugin.overrides : [];
-            plugin.manifest.permissions = normalizedPerms;
             plugin.removeTools = Array.isArray(plugin.removeTools)
                 ? plugin.removeTools
                 : normalizedPerms.tools?.remove || [];