web-agent-bridge 2.4.0 → 2.6.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/replay.js

@@ -0,0 +1,264 @@
+'use strict';
+
+/**
+ * Deterministic Replay Engine
+ *
+ * Records all task inputs/outputs/side-effects for deterministic replay.
+ * Enables debugging, testing, and verification of agent workflows.
+ */
+
+const crypto = require('crypto');
+const { bus } = require('../runtime/event-bus');
+
+class ReplayEngine {
+  constructor() {
+    this._recordings = new Map();  // taskId → Recording
+    this._maxRecordings = 5000;
+    this._recordingEnabled = true;
+  }
+
+  /**
+   * Start recording a task execution
+   */
+  startRecording(taskId, input) {
+    if (!this._recordingEnabled) return null;
+
+    const recording = {
+      id: `rec_${crypto.randomBytes(8).toString('hex')}`,
+      taskId,
+      input: this._deepClone(input),
+      steps: [],
+      sideEffects: [],
+      startedAt: Date.now(),
+      completedAt: null,
+      output: null,
+      error: null,
+      checksum: null,
+      replayable: true,
+    };
+
+    this._recordings.set(taskId, recording);
+    this._evict();
+    return recording.id;
+  }
+
+  /**
+   * Record a step in the execution
+   */
+  recordStep(taskId, step) {
+    const rec = this._recordings.get(taskId);
+    if (!rec) return;
+
+    rec.steps.push({
+      index: rec.steps.length,
+      type: step.type,
+      action: step.action,
+      input: this._deepClone(step.input),
+      output: this._deepClone(step.output),
+      duration: step.duration || 0,
+      timestamp: Date.now(),
+    });
+  }
+
+  /**
+   * Record a side effect (network call, DOM mutation, storage write, etc.)
+   */
+  recordSideEffect(taskId, effect) {
+    const rec = this._recordings.get(taskId);
+    if (!rec) return;
+
+    rec.sideEffects.push({
+      index: rec.sideEffects.length,
+      type: effect.type,    // 'network', 'dom', 'storage', 'event'
+      target: effect.target,
+      data: this._deepClone(effect.data),
+      timestamp: Date.now(),
+      reversible: effect.reversible !== false,
+    });
+  }
+
+  /**
+   * Complete a recording
+   */
+  completeRecording(taskId, output, error = null) {
+    const rec = this._recordings.get(taskId);
+    if (!rec) return null;
+
+    rec.completedAt = Date.now();
+    rec.output = this._deepClone(output);
+    rec.error = error ? { message: error.message, code: error.code } : null;
+    rec.checksum = this._computeChecksum(rec);
+
+    bus.emit('replay.recording.complete', { taskId, recordingId: rec.id, steps: rec.steps.length });
+    return rec;
+  }
+
+  /**
+   * Replay a recorded task
+   * Returns the replay plan (steps to execute) with recorded outputs for verification
+   */
+  async replay(taskId, options = {}) {
+    const rec = this._recordings.get(taskId);
+    if (!rec) throw new Error(`No recording found for task ${taskId}`);
+    if (!rec.completedAt) throw new Error('Recording not yet complete');
+
+    const replayResult = {
+      recordingId: rec.id,
+      taskId,
+      originalInput: rec.input,
+      originalOutput: rec.output,
+      steps: [],
+      match: true,
+      verificationMode: options.verify !== false,
+      replayedAt: Date.now(),
+    };
+
+    // In verification mode, run each step and compare outputs
+    if (options.executor && options.verify !== false) {
+      for (const step of rec.steps) {
+        try {
+          const replayOutput = await options.executor(step);
+          const outputMatch = this._deepEqual(step.output, replayOutput);
+
+          replayResult.steps.push({
+            index: step.index,
+            action: step.action,
+            originalOutput: step.output,
+            replayOutput,
+            match: outputMatch,
+          });
+
+          if (!outputMatch) {
+            replayResult.match = false;
+            if (!options.continueOnMismatch) break;
+          }
+        } catch (err) {
+          replayResult.steps.push({
+            index: step.index,
+            action: step.action,
+            error: err.message,
+            match: false,
+          });
+          replayResult.match = false;
+          if (!options.continueOnMismatch) break;
+        }
+      }
+    } else {
+      // Dry-run mode: just return the recorded steps
+      replayResult.steps = rec.steps.map(s => ({
+        index: s.index,
+        action: s.action,
+        input: s.input,
+        output: s.output,
+        duration: s.duration,
+      }));
+    }
+
+    bus.emit('replay.completed', { taskId, match: replayResult.match });
+    return replayResult;
+  }
+
+  /**
+   * Get recording
+   */
+  getRecording(taskId) {
+    return this._recordings.get(taskId) || null;
+  }
+
+  /**
+   * List recordings
+   */
+  listRecordings(limit = 50) {
+    const all = Array.from(this._recordings.values());
+    return all.slice(-limit).reverse().map(r => ({
+      id: r.id,
+      taskId: r.taskId,
+      steps: r.steps.length,
+      sideEffects: r.sideEffects.length,
+      startedAt: r.startedAt,
+      completedAt: r.completedAt,
+      hasError: !!r.error,
+      checksum: r.checksum,
+    }));
+  }
+
+  /**
+   * Compare two recordings
+   */
+  diff(taskId1, taskId2) {
+    const r1 = this._recordings.get(taskId1);
+    const r2 = this._recordings.get(taskId2);
+    if (!r1 || !r2) return null;
+
+    const diffs = [];
+    const maxSteps = Math.max(r1.steps.length, r2.steps.length);
+
+    for (let i = 0; i < maxSteps; i++) {
+      const s1 = r1.steps[i];
+      const s2 = r2.steps[i];
+
+      if (!s1 || !s2) {
+        diffs.push({ index: i, type: 'missing', in: s1 ? 'recording2' : 'recording1' });
+      } else if (!this._deepEqual(s1.output, s2.output)) {
+        diffs.push({ index: i, type: 'output_mismatch', action: s1.action, output1: s1.output, output2: s2.output });
+      }
+    }
+
+    return {
+      match: diffs.length === 0,
+      inputMatch: this._deepEqual(r1.input, r2.input),
+      outputMatch: this._deepEqual(r1.output, r2.output),
+      diffs,
+    };
+  }
+
+  /**
+   * Enable/disable recording
+   */
+  setEnabled(enabled) {
+    this._recordingEnabled = enabled;
+  }
+
+  getStats() {
+    return {
+      totalRecordings: this._recordings.size,
+      enabled: this._recordingEnabled,
+      maxRecordings: this._maxRecordings,
+    };
+  }
+
+  // ── Internal ──
+
+  _computeChecksum(rec) {
+    const data = JSON.stringify({
+      input: rec.input,
+      steps: rec.steps.map(s => ({ action: s.action, output: s.output })),
+      output: rec.output,
+    });
+    return crypto.createHash('sha256').update(data).digest('hex').slice(0, 16);
+  }
+
+  _deepClone(obj) {
+    if (obj === undefined || obj === null) return obj;
+    try {
+      return JSON.parse(JSON.stringify(obj));
+    } catch {
+      return obj;
+    }
+  }
+
+  _deepEqual(a, b) {
+    return JSON.stringify(a) === JSON.stringify(b);
+  }
+
+  _evict() {
+    if (this._recordings.size <= this._maxRecordings) return;
+    const keys = Array.from(this._recordings.keys());
+    const toRemove = keys.slice(0, keys.length - this._maxRecordings);
+    for (const k of toRemove) this._recordings.delete(k);
+  }
+}
+
+const replayEngine = new ReplayEngine();
+
+module.exports = { ReplayEngine, replayEngine };