web-agent-bridge 1.0.0

package/examples/bidi-agent.js

@@ -0,0 +1,119 @@
+/**
+ * Example: AI Agent using WebDriver BiDi Protocol via WAB
+ *
+ * This agent connects to a website using the __wab_bidi interface,
+ * which follows WebDriver BiDi conventions for standardized communication.
+ *
+ * Prerequisites:
+ *   npm install puppeteer
+ *
+ * Usage:
+ *   node examples/bidi-agent.js <url>
+ */
+
+const puppeteer = require('puppeteer');
+
+const TARGET_URL = process.argv[2] || 'http://localhost:3000';
+
+let commandId = 0;
+
+function bidiCommand(method, params = {}) {
+  return { id: ++commandId, method, params };
+}
+
+async function main() {
+  console.log(`\n🔗 WAB BiDi Agent`);
+  console.log(`   Target: ${TARGET_URL}\n`);
+
+  const browser = await puppeteer.launch({ headless: true });
+  const page = await browser.newPage();
+
+  await page.goto(TARGET_URL, { waitUntil: 'networkidle2' });
+  console.log(`✓ Page loaded: ${await page.title()}`);
+
+  // Check for BiDi interface
+  const hasBiDi = await page.evaluate(() => {
+    return typeof window.__wab_bidi !== 'undefined' && typeof window.__wab_bidi.send === 'function';
+  });
+
+  if (!hasBiDi) {
+    console.log('✗ WAB BiDi interface not found on this page.');
+    await browser.close();
+    return;
+  }
+
+  console.log('✓ WAB BiDi interface detected\n');
+
+  // Step 1: Get BiDi context
+  const context = await page.evaluate(() => window.__wab_bidi.getContext());
+  console.log('📋 BiDi Context:');
+  console.log(`   URL: ${context.context.url}`);
+  console.log(`   Title: ${context.context.title}`);
+  console.log(`   Version: ${context.version}`);
+  console.log(`   Tier: ${context.capabilities.tier}`);
+  console.log(`   Capabilities: ${context.capabilities.actions.length} actions\n`);
+
+  // Step 2: Get actions via BiDi command
+  const actionsResult = await page.evaluate((cmd) => {
+    return window.__wab_bidi.send(cmd);
+  }, bidiCommand('wab.getActions'));
+
+  console.log(`🔍 Actions (via BiDi):`);
+  if (actionsResult.result) {
+    actionsResult.result.forEach((action) => {
+      console.log(`   • ${action.name} [${action.trigger}] — ${action.description}`);
+    });
+  }
+
+  // Step 3: Get page info via BiDi
+  const infoResult = await page.evaluate((cmd) => {
+    return window.__wab_bidi.send(cmd);
+  }, bidiCommand('wab.getPageInfo'));
+
+  console.log('\n📄 Page Info (via BiDi):');
+  if (infoResult.result) {
+    console.log(`   Title: ${infoResult.result.title}`);
+    console.log(`   Domain: ${infoResult.result.domain}`);
+    console.log(`   Bridge: v${infoResult.result.bridgeVersion}`);
+  }
+
+  // Step 4: Read content via BiDi command
+  const readResult = await page.evaluate((cmd) => {
+    return window.__wab_bidi.send(cmd);
+  }, bidiCommand('wab.readContent', { selector: 'h1' }));
+
+  if (readResult.result && readResult.result.success) {
+    console.log(`\n📖 Content: "${readResult.result.text}"`);
+  }
+
+  // Step 5: Execute an action via BiDi
+  const actions = actionsResult.result || [];
+  const firstAction = actions.find((a) => a.trigger === 'click');
+  if (firstAction) {
+    console.log(`\n▶ Executing via BiDi: "${firstAction.name}"`);
+    const execResult = await page.evaluate((cmd) => {
+      return window.__wab_bidi.send(cmd);
+    }, bidiCommand('wab.executeAction', { name: firstAction.name }));
+
+    const r = execResult.result;
+    console.log(`   Result: ${r && r.success ? '✓ Success' : '✗ ' + (r?.error || 'Unknown error')}`);
+  }
+
+  // Step 6: Test error handling
+  console.log('\n🧪 Testing error handling:');
+  const errorResult = await page.evaluate((cmd) => {
+    return window.__wab_bidi.send(cmd);
+  }, bidiCommand('wab.unknownMethod'));
+
+  if (errorResult.error) {
+    console.log(`   ✓ Unknown command handled: ${errorResult.error.code} — ${errorResult.error.message}`);
+  }
+
+  console.log('\n✓ BiDi agent session complete.');
+  await browser.close();
+}
+
+main().catch((err) => {
+  console.error('Agent error:', err.message);
+  process.exit(1);
+});

package/examples/puppeteer-agent.js

@@ -0,0 +1,108 @@
+/**
+ * Example: Basic AI Agent using Puppeteer + WAB
+ *
+ * This agent connects to a website that has the Web Agent Bridge script installed,
+ * discovers available actions, and executes them.
+ *
+ * Prerequisites:
+ *   npm install puppeteer
+ *
+ * Usage:
+ *   node examples/puppeteer-agent.js <url>
+ */
+
+const puppeteer = require('puppeteer');
+
+const TARGET_URL = process.argv[2] || 'http://localhost:3000';
+
+async function main() {
+  console.log(`\n🤖 WAB Puppeteer Agent`);
+  console.log(`   Target: ${TARGET_URL}\n`);
+
+  const browser = await puppeteer.launch({ headless: true });
+  const page = await browser.newPage();
+
+  // Navigate to the target site
+  await page.goto(TARGET_URL, { waitUntil: 'networkidle2' });
+  console.log(`✓ Page loaded: ${await page.title()}`);
+
+  // Wait for WAB bridge to be ready
+  const hasBridge = await page.evaluate(() => {
+    return new Promise((resolve) => {
+      if (window.AICommands && window.AICommands._ready) {
+        resolve(true);
+      } else {
+        // Wait up to 5 seconds for bridge
+        const timeout = setTimeout(() => resolve(false), 5000);
+        document.addEventListener('wab:ready', () => {
+          clearTimeout(timeout);
+          resolve(true);
+        });
+      }
+    });
+  });
+
+  if (!hasBridge) {
+    console.log('✗ Web Agent Bridge not found on this page.');
+    await browser.close();
+    return;
+  }
+
+  console.log('✓ Web Agent Bridge detected\n');
+
+  // Step 1: Get page info
+  const pageInfo = await page.evaluate(() => window.AICommands.getPageInfo());
+  console.log('📄 Page Info:');
+  console.log(`   Title: ${pageInfo.title}`);
+  console.log(`   URL: ${pageInfo.url}`);
+  console.log(`   Bridge Version: ${pageInfo.bridgeVersion}`);
+  console.log(`   Tier: ${pageInfo.tier}`);
+  console.log(`   Actions Available: ${pageInfo.actionsCount}`);
+  console.log(`   Rate Limit Remaining: ${pageInfo.rateLimitRemaining}\n`);
+
+  // Step 2: Discover all available actions
+  const actions = await page.evaluate(() => window.AICommands.getActions());
+  console.log(`🔍 Discovered ${actions.length} actions:`);
+  actions.forEach((action) => {
+    console.log(`   • ${action.name} (${action.trigger}) — ${action.description}`);
+    if (action.fields) {
+      action.fields.forEach((f) => {
+        console.log(`     └─ ${f.name}: ${f.type}${f.required ? ' (required)' : ''}`);
+      });
+    }
+  });
+
+  // Step 3: Read content from the page
+  const content = await page.evaluate(() => {
+    return window.AICommands.readContent('h1') || window.AICommands.readContent('title');
+  });
+  if (content && content.success) {
+    console.log(`\n📖 Page heading: "${content.text}"`);
+  }
+
+  // Step 4: Execute a click action (first available)
+  const clickAction = actions.find((a) => a.trigger === 'click');
+  if (clickAction) {
+    console.log(`\n▶ Executing action: "${clickAction.name}"`);
+    const result = await page.evaluate(
+      (name) => window.AICommands.execute(name),
+      clickAction.name
+    );
+    console.log(`   Result: ${result.success ? '✓ Success' : '✗ ' + result.error}`);
+  }
+
+  // Step 5: List permissions
+  const permissions = pageInfo.permissions;
+  console.log('\n🔐 Permissions:');
+  Object.entries(permissions).forEach(([key, value]) => {
+    console.log(`   ${value ? '✓' : '✗'} ${key}`);
+  });
+
+  console.log('\n✓ Agent session complete.');
+  await browser.close();
+}
+
+main().catch((err) => {
+  console.error('Agent error:', err.message);
+  process.exit(1);
+});

package/examples/vision-agent.js

@@ -0,0 +1,159 @@
+/**
+ * Example: Vision-based AI Agent using WAB
+ *
+ * This agent demonstrates how a "vision" or "natural language" AI agent
+ * (like OpenAI Operator, Claude Computer Use, etc.) can interact with
+ * WAB using descriptive intent instead of explicit action names.
+ *
+ * The agent describes what it wants to do in natural language,
+ * and the IntentResolver matches it to available WAB actions.
+ *
+ * Prerequisites:
+ *   npm install puppeteer
+ *
+ * Usage:
+ *   node examples/vision-agent.js <url>
+ */
+
+const puppeteer = require('puppeteer');
+
+const TARGET_URL = process.argv[2] || 'http://localhost:3000';
+
+// ─── Intent Resolver: maps natural language to WAB actions ────────────
+class IntentResolver {
+  constructor(actions) {
+    this.actions = actions;
+  }
+
+  /**
+   * Find the best matching action for a natural language intent.
+   * Uses keyword matching and description similarity.
+   * @param {string} intent — Natural language description (e.g., "sign up for an account")
+   * @returns {{ action: object, confidence: number } | null}
+   */
+  resolve(intent) {
+    const intentLower = intent.toLowerCase();
+    const intentWords = intentLower.split(/\s+/);
+    let bestMatch = null;
+    let bestScore = 0;
+
+    for (const action of this.actions) {
+      const descLower = (action.description + ' ' + action.name).toLowerCase();
+      let score = 0;
+
+      // Exact name match
+      if (intentLower.includes(action.name.replace(/_/g, ' '))) {
+        score += 5;
+      }
+
+      // Word overlap scoring
+      for (const word of intentWords) {
+        if (word.length < 3) continue;
+        if (descLower.includes(word)) score += 1;
+      }
+
+      // Category bonus
+      if (action.category === 'navigation' && /navigate|go to|open|visit/i.test(intent)) score += 2;
+      if (action.trigger === 'fill_and_submit' && /fill|submit|sign up|register|login|form/i.test(intent)) score += 2;
+      if (action.trigger === 'click' && /click|press|tap|select|button/i.test(intent)) score += 1;
+
+      // Synonym matching
+      const synonyms = {
+        'sign up': ['register', 'create account', 'signup'],
+        'log in': ['login', 'sign in', 'signin'],
+        'search': ['find', 'look for', 'query'],
+        'submit': ['send', 'post', 'confirm'],
+        'navigate': ['go to', 'open', 'visit']
+      };
+
+      for (const [key, syns] of Object.entries(synonyms)) {
+        if (syns.some(s => intentLower.includes(s)) && descLower.includes(key)) score += 3;
+        if (intentLower.includes(key) && syns.some(s => descLower.includes(s))) score += 3;
+      }
+
+      if (score > bestScore) {
+        bestScore = score;
+        bestMatch = action;
+      }
+    }
+
+    if (!bestMatch || bestScore < 1) return null;
+
+    const confidence = Math.min(1, bestScore / 10);
+    return { action: bestMatch, confidence };
+  }
+}
+
+// ─── Vision Agent ─────────────────────────────────────────────────────
+async function main() {
+  console.log(`\n👁️  WAB Vision Agent`);
+  console.log(`   Target: ${TARGET_URL}\n`);
+
+  const browser = await puppeteer.launch({ headless: true });
+  const page = await browser.newPage();
+
+  await page.goto(TARGET_URL, { waitUntil: 'networkidle2' });
+  console.log(`✓ Page loaded: ${await page.title()}`);
+
+  // Wait for bridge
+  await page.waitForFunction(() => typeof window.AICommands !== 'undefined', { timeout: 10000 });
+  console.log('✓ WAB bridge detected\n');
+
+  // Get available actions
+  const actions = await page.evaluate(() => window.AICommands.getActions());
+  const resolver = new IntentResolver(actions);
+
+  console.log(`📋 Available actions: ${actions.length}`);
+  actions.forEach(a => console.log(`   • ${a.name} — ${a.description}`));
+
+  // ── Simulate vision agent intents ─────────────────────────────────
+  const intents = [
+    'I want to create a new account',
+    'Take me to the documentation page',
+    'Click the login button',
+    'Show me the dashboard'
+  ];
+
+  console.log('\n🧠 Resolving natural language intents:\n');
+
+  for (const intent of intents) {
+    const match = resolver.resolve(intent);
+
+    if (match) {
+      console.log(`  Intent: "${intent}"`);
+      console.log(`  → Action: ${match.action.name} (${match.action.trigger})`);
+      console.log(`  → Confidence: ${(match.confidence * 100).toFixed(0)}%`);
+      console.log(`  → Description: ${match.action.description}`);
+
+      // Execute if confidence is high enough
+      if (match.confidence >= 0.3) {
+        const result = await page.evaluate(
+          (name) => window.AICommands.execute(name),
+          match.action.name
+        );
+        console.log(`  → Executed: ${result.success ? '✓' : '✗ ' + result.error}`);
+      } else {
+        console.log(`  → Skipped: confidence too low`);
+      }
+    } else {
+      console.log(`  Intent: "${intent}"`);
+      console.log(`  → No matching action found`);
+    }
+    console.log('');
+  }
+
+  // ── Demonstrate page info with security context ───────────────────
+  const pageInfo = await page.evaluate(() => window.AICommands.getPageInfo());
+  console.log('📊 Page Info:');
+  console.log(`   Security sandbox: ${pageInfo.security.sandboxActive ? '✓ Active' : '✗ Inactive'}`);
+  console.log(`   Self-healing: ${pageInfo.selfHealing.tracked} tracked, ${pageInfo.selfHealing.healed} healed`);
+  console.log(`   Stealth mode: ${pageInfo.stealthMode ? 'Enabled' : 'Disabled'}`);
+
+  console.log('\n✓ Vision agent session complete.');
+  await browser.close();
+}
+
+main().catch((err) => {
+  console.error('Agent error:', err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "web-agent-bridge",
+  "version": "1.0.0",
+  "description": "Open-source middleware that bridges AI agents and websites — providing a standardized command interface for intelligent automation",
+  "main": "server/index.js",
+  "bin": {
+    "web-agent-bridge": "./bin/cli.js",
+    "wab": "./bin/cli.js"
+  },
+  "scripts": {
+    "start": "node server/index.js",
+    "dev": "node server/index.js",
+    "test": "jest --forceExit --detectOpenHandles",
+    "build:script": "node scripts/build.js",
+    "prepublishOnly": "npm test"
+  },
+  "keywords": [
+    "ai",
+    "agent",
+    "bridge",
+    "automation",
+    "web",
+    "middleware",
+    "ai-agent",
+    "browser-automation",
+    "webdriver-bidi"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/abokenan444/web-agent-bridge.git"
+  },
+  "homepage": "https://github.com/abokenan444/web-agent-bridge#readme",
+  "bugs": {
+    "url": "https://github.com/abokenan444/web-agent-bridge/issues"
+  },
+  "files": [
+    "bin/",
+    "server/",
+    "public/",
+    "script/",
+    "sdk/",
+    "examples/",
+    "README.md",
+    "README.ar.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "bcryptjs": "^2.4.3",
+    "better-sqlite3": "^11.6.0",
+    "cors": "^2.8.5",
+    "dotenv": "^16.4.5",
+    "express": "^4.21.0",
+    "express-rate-limit": "^7.4.1",
+    "helmet": "^8.0.0",
+    "jsonwebtoken": "^9.0.2",
+    "uuid": "^10.0.0",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "jest": "^30.3.0",
+    "supertest": "^7.2.2"
+  }
+}