web-agent-bridge 2.4.0 → 2.5.0

package/server/runtime/event-bus.js

@@ -0,0 +1,210 @@
+'use strict';
+
+/**
+ * WAB Runtime - Event Bus
+ * 
+ * Async event system with typed events, middleware, replay buffer,
+ * and dead-letter queue. This is the nervous system of the Agent OS.
+ */
+
+const crypto = require('crypto');
+
+class EventBus {
+  constructor(options = {}) {
+    this._listeners = new Map();     // event → Set<{ id, handler, filter, once }>
+    this._middleware = [];           // global middleware
+    this._history = [];              // event replay buffer
+    this._deadLetter = [];           // failed events
+    this._maxHistory = options.maxHistory || 10000;
+    this._maxDeadLetter = options.maxDeadLetter || 1000;
+    this._stats = { emitted: 0, delivered: 0, failed: 0, dropped: 0 };
+  }
+
+  /**
+   * Subscribe to an event
+   * @returns {string} subscription ID for unsubscribe
+   */
+  on(event, handler, options = {}) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    const sub = {
+      id: `sub_${crypto.randomBytes(8).toString('hex')}`,
+      handler,
+      filter: options.filter || null,
+      once: options.once || false,
+      priority: options.priority || 0,
+    };
+    this._listeners.get(event).add(sub);
+    return sub.id;
+  }
+
+  /**
+   * Subscribe once
+   */
+  once(event, handler, options = {}) {
+    return this.on(event, handler, { ...options, once: true });
+  }
+
+  /**
+   * Unsubscribe by subscription ID
+   */
+  off(subId) {
+    for (const [, subs] of this._listeners) {
+      for (const sub of subs) {
+        if (sub.id === subId) { subs.delete(sub); return true; }
+      }
+    }
+    return false;
+  }
+
+  /**
+   * Remove all listeners for an event
+   */
+  removeAll(event) {
+    if (event) this._listeners.delete(event);
+    else this._listeners.clear();
+  }
+
+  /**
+   * Emit an event
+   */
+  async emit(event, data, metadata = {}) {
+    const envelope = {
+      id: `evt_${crypto.randomBytes(12).toString('hex')}`,
+      event,
+      data,
+      metadata: {
+        ...metadata,
+        timestamp: Date.now(),
+        source: metadata.source || 'system',
+      },
+    };
+
+    // Run global middleware
+    for (const mw of this._middleware) {
+      try {
+        const result = await mw(envelope);
+        if (result === false) {
+          this._stats.dropped++;
+          return envelope;
+        }
+      } catch (_) { /* middleware errors don't block */ }
+    }
+
+    // Store in history
+    this._history.push(envelope);
+    if (this._history.length > this._maxHistory) {
+      this._history = this._history.slice(-Math.floor(this._maxHistory * 0.8));
+    }
+
+    this._stats.emitted++;
+
+    // Get listeners (event + wildcard)
+    const listeners = [];
+    const exact = this._listeners.get(event);
+    if (exact) for (const sub of exact) listeners.push(sub);
+    const wild = this._listeners.get('*');
+    if (wild) for (const sub of wild) listeners.push(sub);
+
+    // Also match namespace wildcards: 'task.*' matches 'task.completed'
+    for (const [pattern, subs] of this._listeners) {
+      if (pattern === event || pattern === '*') continue;
+      if (pattern.endsWith('.*') && event.startsWith(pattern.slice(0, -1))) {
+        for (const sub of subs) listeners.push(sub);
+      }
+    }
+
+    // Sort by priority (higher first)
+    listeners.sort((a, b) => b.priority - a.priority);
+
+    // Dispatch
+    const toRemove = [];
+    for (const sub of listeners) {
+      try {
+        if (sub.filter && !sub.filter(envelope.data, envelope.metadata)) continue;
+        await sub.handler(envelope.data, envelope.metadata, envelope);
+        this._stats.delivered++;
+        if (sub.once) toRemove.push(sub);
+      } catch (err) {
+        this._stats.failed++;
+        this._deadLetter.push({ envelope, error: err.message, subscriberId: sub.id, timestamp: Date.now() });
+        if (this._deadLetter.length > this._maxDeadLetter) {
+          this._deadLetter = this._deadLetter.slice(-Math.floor(this._maxDeadLetter * 0.8));
+        }
+      }
+    }
+
+    // Cleanup one-time subs
+    for (const sub of toRemove) {
+      for (const [, subs] of this._listeners) subs.delete(sub);
+    }
+
+    return envelope;
+  }
+
+  /**
+   * Add global middleware
+   */
+  use(middleware) {
+    this._middleware.push(middleware);
+  }
+
+  /**
+   * Replay events matching filter since a timestamp
+   */
+  async replay(since, filter, handler) {
+    const events = this._history.filter(
+      e => e.metadata.timestamp >= since && (!filter || filter(e))
+    );
+    for (const e of events) {
+      await handler(e.data, e.metadata, e);
+    }
+    return events.length;
+  }
+
+  /**
+   * Wait for a specific event (returns a promise)
+   */
+  waitFor(event, timeout = 30000, filter = null) {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.off(subId);
+        reject(new Error(`Timeout waiting for event: ${event}`));
+      }, timeout);
+
+      const subId = this.once(event, (data, meta) => {
+        clearTimeout(timer);
+        resolve({ data, meta });
+      }, { filter });
+    });
+  }
+
+  /**
+   * Get dead letter queue
+   */
+  getDeadLetters(limit = 50) {
+    return this._deadLetter.slice(-limit);
+  }
+
+  /**
+   * Get stats
+   */
+  getStats() {
+    return {
+      ...this._stats,
+      listeners: this._countListeners(),
+      historySize: this._history.length,
+      deadLetterSize: this._deadLetter.length,
+    };
+  }
+
+  _countListeners() {
+    let count = 0;
+    for (const [, subs] of this._listeners) count += subs.size;
+    return count;
+  }
+}
+
+// Singleton event bus for the runtime
+const bus = new EventBus();
+
+module.exports = { EventBus, bus };

package/server/runtime/index.js

@@ -0,0 +1,233 @@
+'use strict';
+
+/**
+ * WAB Runtime - Main Entry Point
+ * 
+ * The Runtime is the core of the Agent OS. It provides:
+ * - Task scheduling with retries and timeouts
+ * - Agent state management with checkpoints
+ * - Execution sandboxing
+ * - Event-driven architecture
+ * 
+ * This is NOT a browser wrapper - it's a real execution runtime
+ * comparable to Ray or Temporal.
+ */
+
+const { EventBus, bus } = require('./event-bus');
+const { Scheduler, TaskState } = require('./scheduler');
+const { StateManager } = require('./state-manager');
+const { ExecutionSandbox } = require('./sandbox');
+
+class WABRuntime {
+  constructor(options = {}) {
+    this.scheduler = new Scheduler({
+      maxConcurrent: options.maxConcurrentTasks || 20,
+      maxQueueSize: options.maxQueueSize || 1000,
+      defaultRetries: options.defaultRetries || 3,
+      defaultTimeout: options.defaultTimeout || 30000,
+    });
+
+    this.state = new StateManager({
+      maxCheckpoints: options.maxCheckpoints || 50,
+      ttl: options.stateTTL || 24 * 3600_000,
+    });
+
+    this.sandbox = new ExecutionSandbox({
+      maxConcurrent: options.maxSandboxes || 100,
+      defaultTimeout: options.sandboxTimeout || 30000,
+    });
+
+    this.events = bus;
+    this._started = false;
+    this._cleanupTimer = null;
+
+    // Register built-in task handlers
+    this._registerBuiltinHandlers();
+
+    // Wire events
+    this._wireEventHandlers();
+  }
+
+  /**
+   * Start the runtime
+   */
+  start() {
+    if (this._started) return;
+    this._started = true;
+
+    // Periodic cleanup
+    this._cleanupTimer = setInterval(() => {
+      this.state.cleanup();
+      this.sandbox.cleanup();
+    }, 600_000); // 10 min
+    if (this._cleanupTimer.unref) this._cleanupTimer.unref();
+
+    this.events.emit('runtime.started', {
+      timestamp: Date.now(),
+      capabilities: this.getCapabilities(),
+    });
+  }
+
+  /**
+   * Stop the runtime
+   */
+  stop() {
+    if (!this._started) return;
+    this._started = false;
+    if (this._cleanupTimer) clearInterval(this._cleanupTimer);
+    this.events.emit('runtime.stopped', { timestamp: Date.now() });
+  }
+
+  /**
+   * Submit a task
+   */
+  submitTask(task) {
+    if (!this._started) throw new Error('Runtime not started');
+    return this.scheduler.submit(task);
+  }
+
+  /**
+   * Execute a task in a sandbox with full lifecycle
+   */
+  async executeInSandbox(taskId, handler, options = {}) {
+    // Create sandbox
+    const sbx = this.sandbox.create(taskId, options);
+
+    // Save initial state
+    this.state.save(taskId, { status: 'sandbox_created', sandboxId: sbx.id });
+    this.state.checkpoint(taskId, 'pre-execution');
+
+    try {
+      const result = await this.sandbox.execute(sbx.id, handler);
+
+      if (result.success) {
+        this.state.save(taskId, { status: 'completed', result: result.result });
+      } else {
+        this.state.save(taskId, { status: 'failed', error: result.error });
+      }
+
+      return result;
+    } finally {
+      // Cleanup sandbox after a delay
+      setTimeout(() => this.sandbox.destroy(sbx.id), 60000);
+    }
+  }
+
+  /**
+   * Register a task type handler
+   */
+  registerTaskHandler(taskType, handler) {
+    this.scheduler.registerHandler(taskType, handler);
+  }
+
+  /**
+   * Get runtime capabilities for protocol exposure
+   */
+  getCapabilities() {
+    return {
+      scheduler: { maxConcurrent: 20, retries: true, deadlines: true, dependencies: true },
+      state: { checkpoints: true, rollback: true, ttl: true },
+      sandbox: { isolation: true, resourceLimits: true, auditTrail: true },
+      events: { async: true, replay: true, wildcards: true, deadLetter: true },
+    };
+  }
+
+  /**
+   * Get runtime health and stats
+   */
+  getHealth() {
+    return {
+      status: this._started ? 'running' : 'stopped',
+      uptime: this._started ? Date.now() : 0,
+      scheduler: this.scheduler.getStats(),
+      state: this.state.getStats(),
+      sandbox: this.sandbox.getStats(),
+      events: this.events.getStats(),
+    };
+  }
+
+  // ─── Built-in Handlers ──────────────────────────────────────────────────
+
+  _registerBuiltinHandlers() {
+    // Browser task handler (delegated to data plane)
+    this.scheduler.registerHandler('browser', async (params, ctx) => {
+      ctx.reportProgress(10, 0);
+      // Browser tasks are handled by data-plane executor
+      return { delegated: 'data-plane', params };
+    });
+
+    // API task handler
+    this.scheduler.registerHandler('api', async (params, ctx) => {
+      ctx.reportProgress(10, 0);
+      return { delegated: 'data-plane', params };
+    });
+
+    // Extraction task handler
+    this.scheduler.registerHandler('extraction', async (params, ctx) => {
+      ctx.reportProgress(10, 0);
+      return { delegated: 'data-plane', params };
+    });
+
+    // Workflow (composite) handler
+    this.scheduler.registerHandler('workflow', async (params, ctx) => {
+      const results = [];
+      for (let i = 0; i < ctx.steps.length; i++) {
+        ctx.reportProgress(Math.floor((i / ctx.steps.length) * 100), i);
+        ctx.checkpoint({ step: i, results });
+
+        const step = ctx.steps[i];
+        const handler = this.scheduler._handlers.get(step.type || 'general');
+        if (handler) {
+          const result = await handler(step.params || {}, ctx);
+          results.push({ step: i, result });
+        }
+      }
+      ctx.reportProgress(100, ctx.steps.length);
+      return { steps: results };
+    });
+
+    // Composite task (parallel execution)
+    this.scheduler.registerHandler('composite', async (params, ctx) => {
+      if (!params.tasks || !Array.isArray(params.tasks)) {
+        throw new Error('Composite task requires tasks array');
+      }
+      const promises = params.tasks.map((t, i) => {
+        const handler = this.scheduler._handlers.get(t.type || 'general');
+        if (!handler) return { step: i, error: `No handler for: ${t.type}` };
+        return handler(t.params || {}, ctx).then(r => ({ step: i, result: r }));
+      });
+      return { results: await Promise.allSettled(promises) };
+    });
+
+    // General purpose handler (pass-through)
+    this.scheduler.registerHandler('general', async (params) => {
+      return { received: params };
+    });
+  }
+
+  // ─── Event Wiring ────────────────────────────────────────────────────────
+
+  _wireEventHandlers() {
+    // Track task states in state manager
+    this.events.on('task.started', (data) => {
+      this.state.save(data.taskId, { status: 'running', startedAt: Date.now(), attempt: data.attempt });
+    });
+
+    this.events.on('task.completed', (data) => {
+      this.state.merge(data.taskId, { status: 'completed', duration: data.duration });
+    });
+
+    this.events.on('task.failed', (data) => {
+      this.state.merge(data.taskId, { status: 'failed', error: data.error, attempts: data.attempts });
+    });
+
+    this.events.on('task.progress', (data) => {
+      this.state.merge(data.taskId, { progress: data.progress, currentStep: data.step });
+    });
+  }
+}
+
+// Singleton runtime
+const runtime = new WABRuntime();
+
+module.exports = { WABRuntime, runtime, EventBus, bus, Scheduler, TaskState, StateManager, ExecutionSandbox };

package/server/runtime/sandbox.js

@@ -0,0 +1,266 @@
+'use strict';
+
+/**
+ * WAB Runtime - Execution Sandbox
+ * 
+ * Isolates task execution. Each task runs in its own sandbox with:
+ * - Resource limits (memory, CPU time, network)
+ * - Permission boundaries
+ * - Isolated state
+ * - Audit trail
+ */
+
+const crypto = require('crypto');
+
+class ExecutionSandbox {
+  constructor(options = {}) {
+    this._sandboxes = new Map();
+    this._maxConcurrent = options.maxConcurrent || 100;
+    this._defaultTimeout = options.defaultTimeout || 30000;
+    this._stats = { created: 0, completed: 0, failed: 0, timedOut: 0 };
+  }
+
+  /**
+   * Create a new sandbox for a task
+   */
+  create(taskId, options = {}) {
+    if (this._sandboxes.size >= this._maxConcurrent) {
+      throw new Error('Maximum concurrent sandbox limit reached');
+    }
+
+    const sandbox = {
+      id: `sbx_${crypto.randomBytes(12).toString('hex')}`,
+      taskId,
+      agentId: options.agentId || null,
+      siteId: options.siteId || null,
+
+      // Resource limits
+      limits: {
+        timeout: options.timeout || this._defaultTimeout,
+        maxMemory: options.maxMemory || 128 * 1024 * 1024, // 128MB
+        maxNetworkCalls: options.maxNetworkCalls || 100,
+        maxDomOperations: options.maxDomOperations || 1000,
+        allowedDomains: options.allowedDomains || ['*'],
+        blockedSelectors: options.blockedSelectors || [],
+      },
+
+      // Runtime state
+      state: 'created',
+      usage: {
+        networkCalls: 0,
+        domOperations: 0,
+        startedAt: null,
+        completedAt: null,
+      },
+
+      // Permission boundaries  
+      capabilities: new Set(options.capabilities || []),
+
+      // Audit trail
+      audit: [],
+
+      // Isolated key-value store
+      store: new Map(),
+
+      createdAt: Date.now(),
+    };
+
+    this._sandboxes.set(sandbox.id, sandbox);
+    this._stats.created++;
+    return sandbox;
+  }
+
+  /**
+   * Execute a function within a sandbox
+   */
+  async execute(sandboxId, fn) {
+    const sandbox = this._sandboxes.get(sandboxId);
+    if (!sandbox) throw new Error(`Sandbox not found: ${sandboxId}`);
+    if (sandbox.state !== 'created' && sandbox.state !== 'running') {
+      throw new Error(`Sandbox ${sandboxId} is in state ${sandbox.state}, cannot execute`);
+    }
+
+    sandbox.state = 'running';
+    sandbox.usage.startedAt = Date.now();
+
+    // Create scoped context for the function
+    const context = this._createContext(sandbox);
+
+    try {
+      const result = await _withTimeout(fn(context), sandbox.limits.timeout);
+      sandbox.state = 'completed';
+      sandbox.usage.completedAt = Date.now();
+      this._stats.completed++;
+
+      sandbox.audit.push({
+        action: 'complete',
+        timestamp: Date.now(),
+        duration: sandbox.usage.completedAt - sandbox.usage.startedAt,
+      });
+
+      return { success: true, result, sandbox: this._getSandboxSummary(sandbox) };
+    } catch (err) {
+      sandbox.state = err.message.includes('timed out') ? 'timeout' : 'failed';
+      sandbox.usage.completedAt = Date.now();
+
+      if (sandbox.state === 'timeout') this._stats.timedOut++;
+      else this._stats.failed++;
+
+      sandbox.audit.push({
+        action: sandbox.state,
+        timestamp: Date.now(),
+        error: err.message,
+      });
+
+      return { success: false, error: err.message, sandbox: this._getSandboxSummary(sandbox) };
+    }
+  }
+
+  /**
+   * Create a scoped execution context
+   */
+  _createContext(sandbox) {
+    const self = this;
+    return {
+      taskId: sandbox.taskId,
+      agentId: sandbox.agentId,
+      siteId: sandbox.siteId,
+
+      // Capability check
+      hasCapability(cap) {
+        return sandbox.capabilities.has(cap);
+      },
+
+      requireCapability(cap) {
+        if (!sandbox.capabilities.has(cap)) {
+          throw new Error(`Sandbox lacks capability: ${cap}`);
+        }
+      },
+
+      // Domain check
+      checkDomain(domain) {
+        if (sandbox.limits.allowedDomains[0] === '*') return true;
+        return sandbox.limits.allowedDomains.some(d => domain.endsWith(d));
+      },
+
+      // Resource tracking
+      trackNetworkCall() {
+        sandbox.usage.networkCalls++;
+        if (sandbox.usage.networkCalls > sandbox.limits.maxNetworkCalls) {
+          throw new Error('Network call limit exceeded');
+        }
+      },
+
+      trackDomOperation() {
+        sandbox.usage.domOperations++;
+        if (sandbox.usage.domOperations > sandbox.limits.maxDomOperations) {
+          throw new Error('DOM operation limit exceeded');
+        }
+      },
+
+      // Isolated store
+      set(key, value) { sandbox.store.set(key, value); },
+      get(key) { return sandbox.store.get(key); },
+
+      // Audit
+      log(action, details) {
+        sandbox.audit.push({ action, details, timestamp: Date.now() });
+      },
+
+      // Selector validation
+      checkSelector(selector) {
+        for (const blocked of sandbox.limits.blockedSelectors) {
+          if (selector.includes(blocked)) {
+            throw new Error(`Selector blocked by sandbox policy: ${blocked}`);
+          }
+        }
+        return true;
+      },
+
+      // Read sandbox time remaining
+      get timeRemaining() {
+        if (!sandbox.usage.startedAt) return sandbox.limits.timeout;
+        return Math.max(0, sandbox.limits.timeout - (Date.now() - sandbox.usage.startedAt));
+      },
+    };
+  }
+
+  /**
+   * Get sandbox summary (safe to expose)
+   */
+  _getSandboxSummary(sandbox) {
+    return {
+      id: sandbox.id,
+      taskId: sandbox.taskId,
+      state: sandbox.state,
+      usage: { ...sandbox.usage },
+      auditCount: sandbox.audit.length,
+      duration: sandbox.usage.completedAt
+        ? sandbox.usage.completedAt - sandbox.usage.startedAt
+        : null,
+    };
+  }
+
+  /**
+   * Destroy a sandbox and free resources
+   */
+  destroy(sandboxId) {
+    const sandbox = this._sandboxes.get(sandboxId);
+    if (sandbox) {
+      sandbox.store.clear();
+      this._sandboxes.delete(sandboxId);
+    }
+  }
+
+  /**
+   * Get audit trail for a sandbox
+   */
+  getAudit(sandboxId) {
+    const sandbox = this._sandboxes.get(sandboxId);
+    return sandbox ? [...sandbox.audit] : [];
+  }
+
+  /**
+   * List active sandboxes
+   */
+  listActive() {
+    const active = [];
+    for (const [, sb] of this._sandboxes) {
+      if (sb.state === 'created' || sb.state === 'running') {
+        active.push(this._getSandboxSummary(sb));
+      }
+    }
+    return active;
+  }
+
+  getStats() {
+    return { ...this._stats, active: this._sandboxes.size };
+  }
+
+  /**
+   * Cleanup completed/failed sandboxes older than maxAge
+   */
+  cleanup(maxAge = 3600_000) {
+    const cutoff = Date.now() - maxAge;
+    let cleaned = 0;
+    for (const [id, sb] of this._sandboxes) {
+      if (sb.state !== 'created' && sb.state !== 'running' && sb.createdAt < cutoff) {
+        sb.store.clear();
+        this._sandboxes.delete(id);
+        cleaned++;
+      }
+    }
+    return cleaned;
+  }
+}
+
+function _withTimeout(promise, ms) {
+  if (!ms || ms <= 0) return promise;
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => reject(new Error(`Sandbox execution timed out after ${ms}ms`)), ms);
+    promise.then(r => { clearTimeout(timer); resolve(r); })
+      .catch(e => { clearTimeout(timer); reject(e); });
+  });
+}
+
+module.exports = { ExecutionSandbox };