web-agent-bridge 2.5.0 → 2.7.0

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 };

package/server/runtime/session-engine.js

@@ -0,0 +1,293 @@
+'use strict';
+
+/**
+ * Session Engine
+ *
+ * Manages browser execution sessions with cookies, tokens,
+ * and state persistence across navigation.
+ */
+
+const crypto = require('crypto');
+const { bus } = require('../runtime/event-bus');
+
+class SessionEngine {
+  constructor() {
+    this._sessions = new Map();   // sessionId → BrowserSession
+    this._cookieJars = new Map(); // sessionId → CookieJar
+    this._maxSessions = 500;
+    this._defaultTTL = 3600_000;  // 1 hour
+  }
+
+  /**
+   * Create a new browser execution session
+   */
+  create(config = {}) {
+    const sessionId = `sess_${crypto.randomBytes(16).toString('hex')}`;
+
+    const session = {
+      id: sessionId,
+      agentId: config.agentId || null,
+      siteId: config.siteId || null,
+      state: 'active',
+      viewport: config.viewport || { width: 1920, height: 1080 },
+      userAgent: config.userAgent || null,
+      proxy: config.proxy || null,
+      localStorage: {},
+      sessionStorage: {},
+      variables: {},    // Arbitrary key-value store for the agent
+      history: [],
+      createdAt: Date.now(),
+      expiresAt: Date.now() + (config.ttl || this._defaultTTL),
+      lastActivity: Date.now(),
+    };
+
+    this._sessions.set(sessionId, session);
+    this._cookieJars.set(sessionId, new CookieJar());
+    this._evict();
+
+    bus.emit('session.created', { sessionId, agentId: session.agentId, siteId: session.siteId });
+    return session;
+  }
+
+  /**
+   * Get session
+   */
+  get(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (!session) return null;
+    if (session.expiresAt < Date.now()) {
+      this.destroy(sessionId);
+      return null;
+    }
+    return session;
+  }
+
+  /**
+   * Update session last activity
+   */
+  touch(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (session) session.lastActivity = Date.now();
+  }
+
+  /**
+   * Set cookies for a session
+   */
+  setCookies(sessionId, cookies) {
+    const jar = this._cookieJars.get(sessionId);
+    if (!jar) return;
+    for (const cookie of cookies) {
+      jar.set(cookie);
+    }
+    this.touch(sessionId);
+  }
+
+  /**
+   * Get cookies for a session/domain
+   */
+  getCookies(sessionId, domain = null) {
+    const jar = this._cookieJars.get(sessionId);
+    if (!jar) return [];
+    return jar.getAll(domain);
+  }
+
+  /**
+   * Set localStorage value
+   */
+  setStorage(sessionId, key, value, type = 'local') {
+    const session = this._sessions.get(sessionId);
+    if (!session) return;
+    const store = type === 'session' ? session.sessionStorage : session.localStorage;
+    store[key] = value;
+    this.touch(sessionId);
+  }
+
+  /**
+   * Get localStorage value
+   */
+  getStorage(sessionId, key, type = 'local') {
+    const session = this._sessions.get(sessionId);
+    if (!session) return null;
+    const store = type === 'session' ? session.sessionStorage : session.localStorage;
+    return store[key] || null;
+  }
+
+  /**
+   * Set variable in session
+   */
+  setVariable(sessionId, key, value) {
+    const session = this._sessions.get(sessionId);
+    if (session) {
+      session.variables[key] = value;
+      this.touch(sessionId);
+    }
+  }
+
+  /**
+   * Get variable from session
+   */
+  getVariable(sessionId, key) {
+    const session = this._sessions.get(sessionId);
+    return session?.variables[key] || null;
+  }
+
+  /**
+   * Record navigation in session history
+   */
+  recordNavigation(sessionId, url, title = '') {
+    const session = this._sessions.get(sessionId);
+    if (!session) return;
+    session.history.push({
+      url,
+      title,
+      timestamp: Date.now(),
+      index: session.history.length,
+    });
+    this.touch(sessionId);
+  }
+
+  /**
+   * Export session state (for transfer/persistence)
+   */
+  export(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (!session) return null;
+    return {
+      id: session.id,
+      agentId: session.agentId,
+      siteId: session.siteId,
+      viewport: session.viewport,
+      userAgent: session.userAgent,
+      localStorage: { ...session.localStorage },
+      sessionStorage: { ...session.sessionStorage },
+      variables: { ...session.variables },
+      cookies: this.getCookies(sessionId),
+      history: [...session.history],
+      createdAt: session.createdAt,
+    };
+  }
+
+  /**
+   * Import session state (restore from exported data)
+   */
+  import(data) {
+    const session = this.create({
+      agentId: data.agentId,
+      siteId: data.siteId,
+      viewport: data.viewport,
+      userAgent: data.userAgent,
+    });
+
+    session.localStorage = data.localStorage || {};
+    session.sessionStorage = data.sessionStorage || {};
+    session.variables = data.variables || {};
+    session.history = data.history || [];
+
+    if (data.cookies) {
+      this.setCookies(session.id, data.cookies);
+    }
+
+    return session;
+  }
+
+  /**
+   * Destroy session
+   */
+  destroy(sessionId) {
+    this._sessions.delete(sessionId);
+    this._cookieJars.delete(sessionId);
+    bus.emit('session.destroyed', { sessionId });
+  }
+
+  /**
+   * List sessions
+   */
+  list(filters = {}, limit = 50) {
+    const now = Date.now();
+    let sessions = Array.from(this._sessions.values()).filter(s => s.expiresAt >= now);
+
+    if (filters.agentId) sessions = sessions.filter(s => s.agentId === filters.agentId);
+    if (filters.siteId) sessions = sessions.filter(s => s.siteId === filters.siteId);
+    if (filters.state) sessions = sessions.filter(s => s.state === filters.state);
+
+    return sessions.slice(0, limit).map(s => ({
+      id: s.id,
+      agentId: s.agentId,
+      siteId: s.siteId,
+      state: s.state,
+      historyLength: s.history.length,
+      createdAt: s.createdAt,
+      lastActivity: s.lastActivity,
+    }));
+  }
+
+  getStats() {
+    return {
+      activeSessions: this._sessions.size,
+      maxSessions: this._maxSessions,
+    };
+  }
+
+  _evict() {
+    const now = Date.now();
+    for (const [id, session] of this._sessions) {
+      if (session.expiresAt < now) this.destroy(id);
+    }
+    if (this._sessions.size > this._maxSessions) {
+      const sorted = Array.from(this._sessions.entries())
+        .sort((a, b) => a[1].lastActivity - b[1].lastActivity);
+      const toRemove = sorted.slice(0, sorted.length - this._maxSessions);
+      for (const [id] of toRemove) this.destroy(id);
+    }
+  }
+}
+
+// ─── Cookie Jar ─────────────────────────────────────────────────────────────
+
+class CookieJar {
+  constructor() {
+    this._cookies = new Map();  // domain:name → cookie
+  }
+
+  set(cookie) {
+    const key = `${cookie.domain || '*'}:${cookie.name}`;
+    this._cookies.set(key, {
+      name: cookie.name,
+      value: cookie.value,
+      domain: cookie.domain || '*',
+      path: cookie.path || '/',
+      expires: cookie.expires || null,
+      httpOnly: cookie.httpOnly || false,
+      secure: cookie.secure || false,
+      sameSite: cookie.sameSite || 'Lax',
+      setAt: Date.now(),
+    });
+  }
+
+  get(name, domain = '*') {
+    return this._cookies.get(`${domain}:${name}`) || null;
+  }
+
+  getAll(domain = null) {
+    const now = Date.now();
+    const result = [];
+    for (const cookie of this._cookies.values()) {
+      if (cookie.expires && cookie.expires < now) continue;
+      if (domain && cookie.domain !== '*' && cookie.domain !== domain) continue;
+      result.push({ ...cookie });
+    }
+    return result;
+  }
+
+  delete(name, domain = '*') {
+    this._cookies.delete(`${domain}:${name}`);
+  }
+
+  clear() {
+    this._cookies.clear();
+  }
+}
+
+const sessionEngine = new SessionEngine();
+
+module.exports = { SessionEngine, CookieJar, sessionEngine };

package/server/security/index.js

@@ -184,6 +184,19 @@ class AgentIdentity {
     }
   }
 
+  /**
+   * Validate a session token and return session data
+   */
+  validateSession(token) {
+    const session = this._sessions.get(token);
+    if (!session) return null;
+    if (Date.now() > session.expiresAt) {
+      this._sessions.delete(token);
+      return null;
+    }
+    return session;
+  }
+
   /**
    * Cleanup expired sessions
    */